Keys and authentication

How to create, store, rotate and revoke `sk_live_` keys, the difference between read and write, and the headers every call authenticates with.

An API key is the credential of a system, not of a person. It does not belong to whoever created it: it keeps working if that person leaves the company and gains no permissions if they are promoted. Everything it writes is recorded under the key's name (api_key:<id>), not its creator's.

Creating a key in the app

1. Open Automation and go to the "API Keys" tab. You need to be an analyst or administrator.
2. Press "Generate key". An inline form appears.
3. In "Key name (e.g. 'ERP integration')" type the name of the system that will use it. It is what you will see in the list and in the usage report.
4. Choose the access: "Read only" or "Read and write". It defaults to "Read only": if your integration uploads files or logs orders, change it deliberately.
5. Press "Create". "Key generated — copy it now. It will not be shown again." appears at the top with the full key and a "Copy" button.
6. Press "Copy", paste it into your system's secret manager and close the notice with the ✕.

The key list

Name

The name you gave it when creating it.

Access

"Read" or "Read and write".

Created

The creation date.

Last used

The day of its last call, or "Never". Updated at most once a minute: it tells you whether a key is still in use before you revoke it.

Revoke

Deletes the key. It asks for confirmation: "Revoke this API key? Any apps using it will stop working."

With none yet, the tab says "No API keys yet.". Below the list is the "Developer sandbox" card: see Sandbox and versions.

Read or write

No key can be an administrator. A read key that tries to write gets 403 with error_code: "api_key_scope_insufficient" and error_params: {"required_scope": "write", "key_scope": "read"}. Use the weakest key that does the job: a read key for a BI dashboard or an assistant, a write key only for the process that really writes.

How the key is sent

It goes in the Authorization header with the Bearer prefix. For BI tools that cannot set that header, X-API-Key is accepted too. If you send both, Authorization wins. Never put the key in the URL: proxies and browser history keep URLs.

# The usual way
curl https://app.stockai.es/api/v1/planning -H "Authorization: Bearer sk_live_..."

# For tools that cannot set Authorization (Power BI web connector, Excel Power Query, Looker)
curl https://app.stockai.es/api/v1/planning -H "X-API-Key: sk_live_..."

What a key never reaches

A key reaches almost everything the app does. Some routes belong to a person and not to a system, and answer 403 api_key_route_not_exposed (the reason is in error_params.reason):

• Signing in, users, roles and managing keys themselves (a key cannot create, list or revoke keys).
• Personal preferences, team messages and conversations with the assistant.
• Exporting or deleting the account, installation configuration and the AI provider.
• Decisions that carry a person's name: approving orders, cancelling them or marking them paid, customer commitments, contracts, budgets, forecast adjustments and consensus.
• Configuring file drop (SFTP/S3) and creating a sandbox: an administrator does it on the screen.

HTTP/1.1 403 Forbidden
{"detail":"This endpoint cannot be called with an API key.",
 "error_code":"api_key_route_not_exposed",
 "error_params":{"reason":"internal tag 'users': user and password management belongs to people, not to a credential"}}

Rotating a key without downtime

1. Create a new key with the same access and a name that tells it apart (for example "Nightly ERP 2026-10").
2. Change it in your system's secret manager and deploy.
3. Wait until the old key's "Last used" stops moving and the new one shows today's date.
4. Revoke the old one with "Revoke".

Mind your plan's key ceiling (3 on Pro, 10 on Max): rotating needs a free slot for a few minutes.

Revoking

Revoking is immediate and irreversible: the next call with that key gets 401 api_key_invalid, exactly like a key that never existed (on purpose: whether it existed is not disclosed). The calls it made before still count in the month's usage.

HTTP/1.1 401 Unauthorized
{"detail":"API key is invalid or expired","error_code":"api_key_invalid","error_params":{}}

What is recorded

• Every write by a key is recorded in the account log with the key's name, the route and the outcome.
• What is refused at the door (401, scope or permission 403, 429) leaves no record and does not count as usage: if you write with a read key, you will see it on your side, not in the log.
• Every new key raises the "an API key was created" event, visible to administrators.