Skip to content

Authentication ​

Every request to the Zefi API carries an API key as a bearer token:

http
Authorization: Bearer zefi_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key is zefi_sk_ followed by 43 characters. It is bound to one workspace and carries explicit scopes.

Keep it server-side

A key is a bearer credential: whoever holds it can act as you. It belongs in your backend's secret store — never in browser code, a mobile app, a CI log, or a repository.

Creating a key ​

Keys are created in the Zefi platform, not through the API. Open Settings → API Keys in the workspace the key should act on.

Name it after the system that will use it. The name is how you tell keys apart later, and it is what appears when someone revokes one.

Grant only the scopes that system needs. Write does not imply read — a job that only mints links needs write alone.

ScopeAllows
survey_links:readList and fetch survey links
survey_links:writeCreate and revoke survey links
conversation_metadata:writeSend conversation metadata

Expiry is optional. A key with no expiry works until it is revoked. Setting one is a way to make a temporary integration expire on its own rather than depending on someone remembering.

The secret is shown once ​

At creation the key appears exactly once. Zefi stores a hash, not the key, so a lost secret cannot be recovered or shown again — replace the key instead.

Replacing a key ​

Replace gives an existing key a new secret. It keeps its id, name, scopes and expiry; only the secret changes, and the previous secret stops working immediately. There is no grace window, so deploy the new secret first, or accept a gap.

Replace is the answer to a leaked or lost secret. The integration keeps its identity and its audit trail; only the credential rolls.

Revoking a key ​

Revoke disables a key permanently. Any integration using it starts failing, and it cannot be undone — create a new key instead.

Revocation is not instant

Authorisation decisions are cached at the edge for up to two minutes. A revoked key can still be accepted during that window. If you are responding to a suspected compromise, revoke and then verify, rather than assuming the door shut the moment you clicked.

Revoked keys stay listed under the Revoked tab for 15 days, so a key still deployed somewhere reads as revoked rather than unknown. After that they are removed.

Limits ​

A workspace holds up to 20 active keys. Revoked keys do not count against that.

What a rejected key looks like ​

Authentication is checked at the gateway, before the service runs, so these two responses are plain JSON rather than problem documents:

StatusBodyMeans
401{"message":"Unauthorized"}No Authorization header, or not a bearer token
403{"message":"Forbidden"}Key is malformed, unknown, revoked or expired

A 403 that is a problem document is a different thing — the key is valid but lacks the scope, or belongs to another workspace. See Errors.

Zefi API v1