API keys and scopes

Every request to the Sursa API is made with an API key of your organization. A key belongs to the organization, not to a person: it keeps working when the employee who created it leaves, and what it can do is set on the key itself.

What a key is allowed to do

Three settings of a key decide what a request with it can see and change. Each one only narrows the others.

A key can also be limited to some collections and given an expiry date. A request outside these limits fails: a missing scope returns 403 with the code api_keys.scope, and an object the key cannot see returns 404, exactly as if it did not exist.

Give each integration its own key with the narrowest role and scopes it needs. A sync job that only writes documents does not need admin; a reporting job does not need write scopes.

Create a key

An organization administrator creates keys in Sursa under Administration → API keys, or with POST /v1/api-keys using a key or session that has the admin role:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

The response contains the key value in key. It is shown once: Sursa keeps only a hash of it and cannot show it again. A key looks like kb_ followed by 43 characters; the first characters (prefix) are shown in the list of keys so you can tell keys apart.

Without scopes, the key gets the scopes of its role. Pass scopes to narrow it further. Without expires_at, the key does not expire.

Keep keys secret

• Store keys in a secret manager or in environment variables of your service, never in source code.
• Use keys only from your servers. Sursa accepts requests from browsers (CORS is open), but a key in a web page is visible to everyone who opens it.
• Never send a key in a URL. Send it only in the Authorization header.
• If a key leaks, revoke it at once and create a new one.

Check a key

GET /v1/me returns the key, its role, effective scopes, data profile, expiry and rate limit. It works with any valid key, whatever its scopes, so use it as the connection test of your integration and when you investigate a 403.

Rotate a key

Rotation replaces a key without stopping the integration. The quickest way is to roll the key: POST /v1/api-keys/{key_id}/roll issues a new value for the same key, with the same role, scopes, collections and expiry. The previous value keeps working for overlap_hours (24 hours by default, up to 168), so you can deploy the new value in the meantime; POST /v1/api-keys/{key_id}/revoke-previous ends the overlap early.

To replace a key with a different one instead:

1. Create a new key with the same role, scopes and data profile.
2. Deploy the new key to your integration.
3. Watch the old key in Administration → API keys (or last_used in GET /v1/api-keys) until it is no longer used.
4. Revoke the old key.

Set an expiry date on keys and rotate them before it. Sursa warns the organization's administrators before a key expires; an expired key returns 401 with the code api_keys.expired.

Revoke a key

Revoke a key under Administration → API keys or with DELETE /v1/api-keys/{key_id}. Revocation takes effect within seconds on every API server. Requests with a revoked key return 401 with the code auth.not_authenticated.

Keys of a custom source

A custom source has its own kind of key. It starts with kbsrc_, it can only write documents into that one source, and it cannot read or search anything. It is the safest key to give an integration platform such as Zapier. Create it on the source page under API keys or with POST /v1/sources/{source_id}/push-keys.

When keys are not available

API keys are part of the organization's plan. If the plan does not include them, creating a key and every request with a key return 403 with the code api_keys.feature_disabled.