Authentication
How API keys work, what they can reach, and how to keep them safe.
Every request carries a key as a bearer token:
Authorization: Bearer sgl_live_yourKeyHereThere is no OAuth flow and no refresh step. A key is valid until you revoke it.
Keys
Keys look like sgl_live_ followed by a random string, and they are created in
the app under Settings → Integrations → API & Webhook.
Shown once
The full key appears in the dialog that creates it and nowhere else. We keep only a hash, so there is no way to recover it later. If it goes missing, revoke it and create a new one.
What a key can do:
- Reads one workspace. It sees every document in the workspace it was created in, and nothing in any other workspace, even one you belong to.
- Reads only. Nothing in the API creates, edits or sends documents.
- Manages webhooks. Endpoints are the one thing a key can write.
A workspace can hold up to 10 active keys at once. Give each integration its own, so revoking one never takes down the others.
Where to put it
A key is a server-side secret. It belongs in an environment variable or a secret manager on a machine you control.
Never put one in front-end JavaScript, a mobile app, a browser extension, a public repository, or a URL query string. Anything running on a customer's device is readable by that customer.
Rotate by creating the new key first, deploying it, then revoking the old one. Both work at the same time, so there is no gap.
Failures
| Error | Status | Cause |
|---|---|---|
invalid-api-key | 401 | No Authorization header, a malformed key, or one that has been revoked. |
plan-required | 403 | The key is valid but the workspace is not on Signello Max. |
A 403 means the key itself is fine, so retrying will not help until the workspace is back on Max. A 401 means you need a different key.