Skip to navigation

Authentication

Send a key, an exchanged token or an OIDC token in the Authorization header.
View as Markdown

Every request needs one credential in the Authorization header, except GET /v2/health:

Authorization: Bearer <credential>

Credentials

CredentialFormWhere it comes fromLifetime
API keycrk_{env}_{slug}_…Dash. Read API keys.Until you revoke it, or until its expiry.
Exchanged tokencrt_…POST /v2/oauth/token. Read OIDC trusts.900 seconds by default.
OIDC tokenA JWT from a trusted issuerYour workload. Read OIDC trusts.Set by the issuer.

Each host accepts only the credentials of its own organization. A key of another organization gets 401 invalid_api_key.

Read the credential

GET /v2/me returns the credential of the request. It needs no scope.

curl -s "https://$CRK_SLUG.cloudraker.run/v2/me" \
-H "Authorization: Bearer $CRK_API_KEY"
{
"slug": "acme",
"env": "live",
"scopes": ["parse", "extract", "jobs:read"],
"key": { "id": "key_01JC9M…", "name": "invoices", "hint": "a1B2c3" }
}

For a crt_ token or a JWT, key.id holds the trust id, and key.hint is empty. The Run issuer of your organization has the trust id self.

Scopes

A credential has a list of scopes. There is one list for the host.

GroupScopesGrants
Capabilityparse, extract, classify, split, fill, redact, generate, convert, redline, sign, transcribe, agentsThe capability of the same name.
Jobsjobs:readList the jobs of the environment of the credential. Read the jobs of other credentials in the same environment.
Runrun, read, cancel, git, secrets, admin, preview, act_asRun paths on the same host.

A missing scope gives 403 insufficient_scope. The agent allowlist and the rate cap of a key are restrictions on the key. They are not scopes.

Common errors

StatusCodeCause
401missing_credentialNo Authorization header.
401invalid_api_keyA bad crk_ key, a key of another host, or a revoked or expired key.
401invalid_tokenA crt_ token or a JWT that fails a check.
403insufficient_scopeThe credential does not have the scope, or the agent is not allowed.

Read Errors for all codes.