API keys¶
The hosted API is authenticated with an API key. There are no session cookies and no bearer tokens borrowed from a browser login: a program gets a credential made for programs.
| Property | Value |
|---|---|
| Prefix | aok_ |
| Looked up by | the first 8 characters |
| Secret | 32 random characters |
| Scopes | submit, read, manage:keys |
| Expires | 365 days after it is minted |
What it takes to get one¶
A key is minted only for an account that has been approved for programmatic
access and has accepted the current Terms. The two gates are separate errors —
not_approved and
terms_not_accepted — so you can tell which
one you are behind.
Getting the first key is a one-time interactive step: you prove control of your email address with a one-time code, and mint the key with the short-lived credential that gives you. After that the key is the credential and the browser is not involved again.
Scopes¶
Each key carries the scopes it needs and nothing more. A key that only reads
results cannot spend your quota, and a key on a shared machine need not be able
to mint more keys. Using an operation outside a key's scopes is
forbidden — a distinct answer from
unauthorized, which means no usable credential
was presented at all.
Handling the secret¶
The secret is shown once, when the key is minted, and is never retrievable afterwards: it is stored only as a keyed hash. If you lose it, revoke the key and mint another.
- Put it in an environment variable or a secret manager, not in a notebook, a repository or a shell history.
- One key per machine or per pipeline, so that revoking one does not stop everything.
- Keys expire on their own. An abandoned key is a credential nobody is watching, so expiry is not optional.
Revocation takes effect immediately, and every mint, use and revocation is recorded in an append-only log on the account.
Identifiers¶
Every identifier the API returns is prefixed with the kind of thing it names, so a value that ends up in the wrong argument fails as a wrong kind rather than as a mysterious not-found:
| Resource | Id prefix |
|---|---|
| Job | job_ |
| Upload | upl_ |
| Key | key_ |
| Model | mdl_ |