Authentication

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

Authorization: Bearer zefi_sk_4kQ2xR7vBn9LpZs1Ty6WdEuHgJmA0Cf5TbY8Nr3Vq

A key is bound to one workspace and carries explicit scopes. It is a server-side credential: it belongs in your backend's secret store, never in browser code, a mobile app, 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.

Choose a name describing 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 permissions that system needs:

Permission	Allows
survey_links:read	List and fetch survey links
survey_links:write	Create and revoke survey links

Write does not imply read. A job that only mints links needs write alone.

Optionally set an expiry. A key with no expiry works until it is revoked.

Copy it once

The key appears exactly once, at creation:

zefi_sk_4kQ2xR7vBn9LpZs1Ty6WdEuHgJmA0Cf5TbY8Nr3Vq

Zefi stores a hash, not the key, so a lost key cannot be recovered or shown again. If you lose it, replace it — see below.

Replacing a key

Replace gives the key a new secret. It keeps its name, permissions and expiry; only the secret changes, and the previous secret stops working immediately. Deploy the new one promptly — anything still using the old secret starts failing at once.

Revoking a key

Revoke disables a key permanently. Any integration using it starts failing.

Revocation can take up to two minutes to take effect everywhere, because the API caches authorisation decisions at the edge. Plan for that when rotating away from a key you believe is compromised — revoke, then confirm.

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

Limits

A workspace can hold 20 active keys. Revoked keys do not count.