Authentication

Every request to /api/v1/* carries an API token in the Authorization header:

Authorization: Bearer sgn_R7xq9…

The scheme is case-insensitive; the token is not. Tokens are never accepted in the query string.

Tokens

• Created in Settings → Integrations → API keys by a workspace member. Give each integration its own token, so you can revoke one without breaking the others.
• Format: sgn_ followed by 43 URL-safe base64 characters (47 characters in total).
• Shown once at creation. Seegnals stores only a SHA-256 hash and the first 12 characters, which is what you see in the token list.
• A token belongs to exactly one workspace and gives full access to the API for that workspace. There are no scopes or roles on tokens.
• Revoking sets revoked_at on the token. The next request with it gets 401, immediately. The row stays in the list for audit.
• Last used in the token list updates on every authenticated request.

The 401 responses

Both bodies carry WWW-Authenticate: Bearer realm="Seegnals API".

{ "error": "Missing bearer token." }

The header is absent or does not start with Bearer.

{ "error": "Invalid API token." }

The token has the wrong shape, is unknown, or has been revoked. The API does not tell you which, on purpose.

What you will not see

• 403. A token only ever sees its own workspace. A request for another workspace’s prospect or subscription returns 404, exactly as if the id did not exist.
• 500 on bad auth. A missing or wrong token always ends as 401. This is checked after every deploy.
• OAuth, IP allow-lists, CORS headers. The API is meant to be called from your server, a workflow tool or a script. Calls from a browser page on another origin are not supported.

Good practice

Store the token in your secret manager. Keep it out of your codebase. Rotate by creating a new token, switching the integration, then revoking the old one. If a token leaks, revoke it first and ask questions later; creating a replacement takes ten seconds.