Authentication
API key lifecycle, scopes, and sandbox versus live keys.
The SurfacedBy API authenticates every request with a single bearer token passed in the X-API-Key header. There is no OAuth flow and no session cookies: an API key identifies both who you are and what you are allowed to do.
Minting a key
API keys are created from Settings -> Developer in the dashboard. When you mint a key, SurfacedBy displays the plaintext value exactly once; it is not recoverable after that. Store it in a secret manager and never commit it to source control.
Every key has a display prefix (for example sk_live_aBcDeFgH) that is safe to log and safe to show in UI lists. The full value is only used at request time.
Live versus test keys
Keys come in two flavours:
- Live keys (
sk_live_...) hit real data on your account. Writes create real resources. - Test keys (
sk_test_...) operate against a sandbox-scoped view of the same account. They are subject to the same rate limits as live keys but write into isolated sandbox state, so you can integrate without disturbing production data.
Use test keys during integration development and switch to live keys only once the integration is tested.
Scopes
Keys have scopes that determine what they can do:
read- every GET endpoint in the API. All keys on Professional and Business get this scope.write- POST and DELETE endpoints. Only available on Business.
Professional accounts cannot create a key with the write scope; the API rejects those writes before they reach the handler. This keeps the public API surface honest about what each tier includes.
Rotation
Rotating a key is a two-step process: mint a new key, update your integration to use it, then revoke the old one. Revocation is immediate. SurfacedBy keeps a record of revocation reasons so you can audit rotations later.
Automated rotation is a good practice. We recommend rotating at least once per year, and immediately whenever a key might have been exposed.
Key limits
Each tier caps the number of active keys per account: Professional allows 1, Business allows 3. Revoke an old key before minting a replacement if you hit the cap.
Losing a key
A leaked key should be revoked immediately from settings. All subsequent requests with that key will fail with a 401 response. Mint a fresh key and update your integration.