Skip to navigation

API keys

Create crk_ keys in Dash. Revocation applies on the next request.

View as Markdown

An API key belongs to your organization, not to a person. Only an admin can create a key. Dash manages the keys.

Format

crk_{env}_{slug}_{secret}{tag}
PartExampleMeaning
envlive, testThe environment of the key.
slugacmeThe slug of your organization. The host must have the same slug.
secret43 charactersThe secret part of the key.
tag6 charactersA checksum. The API drops a forged key before any other work.

A key does not work on the host of another organization. A key with a bad format or tag gets 401 invalid_api_key.

Create a key

  1. Open API keys in Dash.
  2. Select Create key.
  3. Enter a name and select the environment and the scopes.
  4. Copy the value.

Optional settings:

SettingEffect
ExpiryThe key stops working at this time.
Rate capThe key has its own requests-per-minute limit, inside the organization limit.
Agent allowlistThe key can start only these Run agents.
Keep a key on your server. Never put a key in a browser, a mobile app or a repository.

Live keys and test keys

BehaviourLive keyTest key
Rate limitsThe limits of your planIts own limits. Read Rate limits.
JobsReal jobsReal jobs. Test keys run the same capabilities.
Paperwork creditsReal creditsReal credits
Value in DashShown one time onlyCan be shown again
Run and /v2/agentsAllowedRefused with 403 test_key_not_allowed
Test keys have their own rate limits, but their jobs use real paperwork credits.

A test key does not give a sandbox. Paperwork has no test credit pool. When the balance of the organization reaches zero, live keys and test keys both get 402 credits_exhausted.

Revoke a key

Select a key in Dash and revoke it. Revocation applies on the next request. An open job stream of the key ends with no terminal event and no job output.

To rotate a key, create the new key, deploy it, then revoke the old key. Dash shows the last-used time of each key.