# Authentication Every request to `https://api.stack.foldbun.com` carries an API key in the `Authorization` header. ```http Authorization: Bearer fbs_... ``` Keys are created in the [console](https://stack.foldbun.com/console/keys) and belong to the account, not to a person. Calls made with any key of an account are billed to that account. ## Email verification A new account must verify an email address before the account's keys can call the API. Until then, calls fail with `403 email_unverified`. ## Key format A key is the prefix `fbs_` followed by 49 base62 characters, 53 characters in total. The last 6 characters are a checksum, so a mistyped or made-up key is rejected with `401 unauthorized` before any lookup. Only a SHA-256 hash of the key is stored. The secret is shown once, when the key is created, and cannot be shown again. A lost key cannot be recovered; create a new key and revoke the old one. ## Model scope A key can be limited to selected models. Scopes use the form `model:`, for example `model:ppocr-v6`. - A key without model scopes can call every model the account may use. - A key with one or more `model:` scopes can call only those models. A call to another model is refused with `403 model_locked`. A scope narrows what a key can do and never widens it. The account's pool decides which models are available at all. See [Rate limits and pools](https://stack.foldbun.com/docs/rate-limits/). ## Expiry A key can be created with an expiration: never, 7, 30, 90 or 365 days, or a custom date in the future. The expiry of an existing key can be changed or cleared later. An expired or revoked key is refused with `401 unauthorized`. ## Revocation and rotation - **Revoke** stops a key immediately. - **Replace** creates a new key with the same name and scopes, and sets the old key to expire after a grace period of up to 7 days. A replacement never extends an earlier expiry of the old key. With no grace period, the old key stops at once. Rotation steps for a deployed key: 1. Replace the key in the console with a grace period. 2. Deploy the new key. 3. Let the old key expire, or revoke it after the deployment. ## Limits - An account can hold at most 100 active keys. - A key name is 1 to 64 characters. - Last use of a key is shown in the console. ## Failures | Status | Code | Meaning | |---|---|---| | 401 | `unauthorized` | The header is missing or malformed, or the key is invalid, expired or revoked. | | 403 | `model_locked` | The key's scope or the account's pool does not allow the model. | | 403 | `email_unverified` | The owner of the key has not verified an email address. | See [Errors](https://stack.foldbun.com/docs/errors/) for the error envelope.