Authentication

Every request to https://api.stack.foldbun.com carries an API key in the Authorization header.

Authorization: Bearer fbs_...

Keys are created in the console 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:<id>, 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:<id> 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.

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 for the error envelope.