Using API keys
Scope a key to exactly what an integration needs, nothing more.
What an API key is for
An API key lets another system — a CRM, your own backend, a Zapier-style integration — call Sumezi's API directly, without signing in as a user. It authenticates the request as belonging to one specific project, the same way a session cookie does for a logged-in person, but it never expires on its own and carries no user identity behind it.
Owner-only: only the workspace owner can create, view, or revoke API keys. If you're logged in with a different role, the panel just looks empty — it fails silently rather than showing a permission error.
Scopes: grant only what's needed
Every key is scoped — restricted to a specific set of endpoints rather than your whole account. Right now there's exactly one scope available: subscribers. A key with this scope can list and search subscribers, add or update one, bulk-import a batch, and read a subscriber's event history. It cannot touch anything else — templates, automations, sends, billing, or your other API keys.
| Scope | Endpoint |
|---|---|
| subscribers | /api/subscribers |
You don't pick a scope when creating a key — there's only one, so it's applied automatically. Scopes are stored as a comma-separated list under the hood, which leaves room for Sumezi to add more scopes later without changing how existing keys work.
Creating a key
- Go to Settings, API keys — you need the owner role for this section to do anything.
- Click "New key" and give it a name that describes what will use it, e.g. "CRM integration" — this is just a label to help you tell keys apart later.
- Copy the full key the moment it's shown. It's displayed exactly once, at creation — Sumezi stores only a SHA-256 hash of it afterwards, not the raw value, so there's no way to retrieve it again later.
- If you lose it, there's no recovery — revoke it and create a new one instead.
What stays visible afterwards: just the key's name, its first 12 characters (e.g. smz_a1b2c3d4…), when it was created, and when it was last used — enough to recognize it, never enough to reconstruct it.
Calling the API with a key
Send the raw key as a bearer token in the Authorization header. It must start with smz_ — that prefix is how Sumezi recognizes an API key at all, as opposed to a user session token; anything else in that header is handled by a completely different authentication path.
curl -H "Authorization: Bearer smz_yourrawkeyhere" "https://yourapp.com/api/subscribers?limit=20"
What happens when a key doesn't fit
Three outcomes cover every case, and they're deliberately distinct so an integration can tell them apart:
| Status | Meaning |
|---|---|
| 200 | key is valid and the endpoint is inside its scope |
| 401 | no valid key at all — missing, malformed, or revoked |
| 403 | key is valid, but the endpoint is outside its scope |
In other words: a working subscribers-scoped key gets a normal 200 from /api/subscribers, the same key gets a 403 the moment it calls anything outside that scope, and once it's revoked it gets a 401 immediately — there's no separate error code specifically for "revoked", since a revoked key simply stops resolving to anything and looks exactly like no key was sent at all.
Revoking a key and common errors
- Revoking is immediate: click the trash icon next to a key and confirm. There's no grace period — any integration still using it gets a 401 on its very next request.
- 401 "Authentication required": the key is missing, revoked, or the header is malformed — double-check it reads exactly
Authorization: Bearer smz_...with no quotes or extra whitespace around the key. - 403 "This API key does not have access to this endpoint": you're calling something outside the
subscribersscope. There's currently no key that reaches templates, automations, sends, or billing — that's expected, not a bug. - The panel looks empty even though keys exist: you're probably not logged in as the workspace owner — key management is owner-only, and the panel fails silently for anyone else.
- Lost the raw key: there's no way to view it again — revoke it and create a replacement.