Send Your Key
Send the key in theAuthorization header as a bearer token:
X-API-Key header is accepted as well:
X-API-Key is the one that is used.
A key is never accepted in the URL or in the request body.
Key Format
A key is 83 characters long. An example with a made-up secret, which is not a working key:
Check a Key Before You Store It
The checksum is not a secret. It lets you catch a truncated or mistyped key without calling the API:foro_live_ and fails it is always refused. The check is for foro_live_ keys only: an older key has no checksum, so do not use it to reject one.
Older Keys
Keys created before the checksum was added have no checksum. Most aresk_live_ followed by 64 hexadecimal characters, and the earliest are 64 hexadecimal characters with no prefix. Both kinds keep working, are sent in the same headers and do not need to be replaced. The check above does not apply to them, so accept them as they are.
Create a Key
A key is created for an account by a member of that account who has access to all of its stores. The account’s plan has to include API keys.- In the dashboard, open Developers & AI.
- On the API keys card, select Manage API keys.
- Select Create API Key.
- Enter a Name that says what will use the key, and choose its Access and when it Expires.
- Copy the key and store it somewhere safe.
- The key is shown once, when it is created. Only a hash of it is stored, so it cannot be shown again. If you lose it, create a new one.
- The key list shows each key’s name and, in the Key column, its first 18 characters, so you can tell your keys apart.
- Expires is set to 90 days unless you choose 30 days, 1 year, Custom date or No expiry.
- The Last used column shows when each key was last used, to within about a minute.
When a Key Is Refused
A request without a key, or with a key that is not accepted, is answered with401 and an error of type authentication_error:
api_key_invalid is the same answer for a mistyped key, a key that was never issued, a revoked key and an expired key. The response does not say which, so that it tells nothing to someone guessing keys. If a key that used to work starts answering 401, check its Status and Expires columns in the key list to see whether it has expired or been revoked.
A 401 will not succeed when retried with the same key. Do not retry it.
A key that is valid but not allowed to make a particular request is answered with 403, not 401. See scope_insufficient and permission_denied.
Keep Your Key Safe
A key gives access to an account’s data, so treat it like a password.- Call the API from your server only. Never put a key in a web page, a mobile app or anything else that is delivered to a user’s device, where it can be read.
- Keep it out of source control. Load it from an environment variable or a secret manager. Do not paste it into code, tickets, chat or support requests. Support never needs your key: send the request ID instead.
- Use one key for each integration and environment, named after what uses it, so that one can be revoked without stopping the others.
- Do not log it. If you need to refer to a key in a log, log its first 18 characters, which is what the key list shows.
Rotate a Key
- Create a new key.
- Deploy it to everything that uses the old one.
- Check in the key list that the old key is no longer being used.
- Revoke the old key.
If a Key Leaks
Select Revoke Key on its row in the key list straight away, then create a new one. A revoked key stops working within a minute and cannot be restored.Find Leaked Keys
To scan your own code and logs for keys, match:sk_live_[0-9a-f]{64}, or 64 hexadecimal characters alone, and cannot be verified offline.