Every request sends the key in the x-api-key header. A key in the query string is not accepted, so it does not land in a log or a browser history.
Live keys start with ss_live_ and then 40 letters and digits. Test keys start with ss_test_. Treat both as passwords.
Keys belong to a team and are managed in the dashboard.
- The full key is shown once, when you create it. Only a hash is stored, so a lost key cannot be shown again. Create a new one.
- A team can hold 20 active keys. Name each one for the app or environment that uses it. The dashboard shows when each key was last used.
- Owners and admins create and revoke keys. Members can see names, not change them.
- To rotate, create the new key, deploy it, then revoke the old one. A revoked key stops working within seconds.
| Situation | Answer |
|---|---|
| Header missing, or the key is malformed, unknown or revoked | 401 unauthorized |
| The key or its team is suspended | 403 forbidden |
| The team has too few credits | 402 insufficient_credits |
Those three failures for a bad key are the same answer on purpose. The error does not say which keys exist.
Read the key from an environment variable or a secrets manager. A key in browser or mobile code is public. If one leaks, revoke it in the dashboard before you create a replacement.
Full detail: Authentication.