#Authentication and Permissions

Status: Available — keys, scopes, permissions, the IP list. Planned — test keys and the sandbox.

Purpose: how integrations and keys work, what scopes mean, how the effective permissions of a request are computed, how to rotate and revoke keys, and what to do when a key leaks.

#The model: tenant → integration → keys

Tenant
 └── Integration "My CRM"  (a service account, no dashboard login)
      ├── integration role (a set of permissions)
      ├── Key A  (scopes, expiry, IP list, mode)
      └── Key B  (issued during rotation; Key A keeps working for up to 24 h)

• An integration is a tenant service account. You cannot sign in to the dashboard with it; it does not appear in operator pickers, mailings, or seat counts. It has its own role and access to all of the tenant's conversations.
• Keys belong to an integration. Rotating a key does not change the integration identifier, so your logs and audit trail stay continuous.
• Every integration is bound to an owner employee, the person who created it. The integration's permissions depend on that employee's current permissions (see below).
• A tenant can have at most 20 active keys.
• An employee with the integrations.manage permission (by default, the owner and the manager) can create integrations and keys. This permission is separate from managing the keys of external providers that the platform itself uses.

#Key format

sap_<cell>_<mode>_<identifier>_<secret>

Example (deliberately fake):

sap_ru_test_EXAMPLE0KEYID_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEX

The platform stores only an irreversible hash of the secret with the cell's server-side pepper. A database leak without the pepper does not reveal the keys.

#How to send the key

Only in the Authorization header, and only over TLS:

GET /api/public/v1/me HTTP/1.1
Host: formula-cream.pro
Authorization: Bearer sap_ru_live_EXAMPLE0KEYID_…

• You must not send the key in the URL (?key=…), the request body, or a cookie.
• In v1, per-request signing is neither required nor supported: protection is built on a Bearer key over TLS. A hardened mode based on the client's public key (Ed25519) is not supported in v1. The signature_invalid code is reserved for it and is not returned in v1.
• A browser or a mobile app must not receive the key: use the client interfaces (Introduction).

#Key lifecycle

#Step-by-step rotation without downtime

1. Issue a new key for the same integration with the same scopes.
2. Deploy the new key to your secret store and restart the services.
3. Use "API usage" in the dashboard to confirm that the old key is no longer called.
4. Revoke the old key. If you forget, it expires on its own at the end of the overlap window.

#Scopes

A scope is a permission you give to a key. Grant the minimum necessary. The "Paid" column shows whether the tenant's wallet is charged. The "PII" column shows whether the responses contain personal data of the tenant's customers.

Notes.

1. The strategist works with aggregates and, by design, does not see personal data; this is verified when the API is released.
2. Event ingestion accepts only pseudonymous identifiers: anonymous_id and user_id are your own pseudonyms. Email, phone, and name in properties are rejected with 422 validation_failed (a JSON Pointer identifies the field), so this scope is not classified as PII.
3. POST /leads/{id}/score is paid and requires leads:score. Writing the external CRM's own score (PUT /leads/{id}/score) is free and requires leads:write.
4. Approving a strategist topic and confirming a strategist action additionally require the permission for what is being proposed and an available budget. Approving a topic does not start article generation.
5. GET /me, GET /wallet, and GET /operations/{id} are available to any valid key and require no scope (GET /me and GET /wallet also work while exchange is suspended; see Wallet); operations are visible only to the integration that created them.
6. A subscription with include_pii: true additionally requires the integration to have leads:read and/or conversations:read (Webhooks).
7. The personal data disclosure log is visible to the tenant in the dashboard and through GET /disclosures (retained for 3 years). Which permission a key needs for this request is not fixed in v1 and will be specified in OpenAPI. For details, see Cells and data.

#Mapping scopes to endpoints

#How the permissions of a request are computed

A request is allowed only if every condition is met. The effective permissions are an intersection:

request permissions = key scopes
                    ∩ integration role
                    ∩ CURRENT permissions of the owner employee
                    ∩ license (api_access) and plan

In addition, the tenant check applies: the tenant must be active. The identifier of another tenant's resource yields 404 not_found.

The consequence for an integrator: a key that worked yesterday can get scope_missing today if the owner's permissions changed. This is normal behavior; handle 403.

#IP allowlist

• Optional: a list of addresses or CIDR networks from which requests with the key are accepted.
• A request from any other address gets 403 ip_not_allowed.
• For scopes with personal data (conversations:*, leads:*) in the RU cell, the integration's IP list is mandatory; a key with such scopes is not issued without it. In addition, when connecting you specify the hosting country of the receiving system and the basis for the transfer; if the country is not Russia, the conversations:* and leads:* scopes are not granted (403 pii_transfer_not_allowed, Cells and data). The current list is visible in GET /me (key.ip_allowlist).
• If you make calls from a cloud with floating addresses, pin the outbound address (a NAT gateway, a static IP).
• Using a key from a new address or a new country raises an alert to the tenant owner.

#Test keys

Status: Planned.

Keys with the test mode (sap_<cell>_test_…) work in the cell's sandbox, a separate tenant with fictitious data.

A production key does not work in the sandbox, and a test key does not work in the production tenant.

#What to do if a key leaks

1. Revoke the key in the dashboard (Settings → API). Revocation takes effect within 60 seconds at most.
2. Issue a new key and update the secrets in your systems.
3. Check the log "API usage" (retained for 90 days; it holds the method, route, status, time, cost, and request_id, with no request bodies and no personal data) and the audit trail: what the key did after the suspected leak date.
4. If the key had scopes with personal data, check the personal data disclosure log (dashboard or GET /disclosures, retained for 3 years) and assess which data may have been disclosed. The data controller's duties to notify regulators and data subjects are determined by the laws of your jurisdiction.
5. Check whether any new webhooks, keys, or integrations were created, and revoke the extras; if in doubt, rotate the webhook secrets.
6. Remove the key from the repository history and from logs; a single deletion commit is not enough.

Prevention: minimal scopes, an IP allowlist, a lifetime shorter than the maximum, separate keys for separate systems, storage in a secrets manager.

#Authentication errors

The response body is application/problem+json with a type of the form https://<cell domain>/developers/errors#<code> (Conventions). The full catalog is in Conventions.

#Notes

• Every write through the API goes into the tenant audit log with the integration and the key (key_id), on behalf of the service account.
• Brute force: keys are looked up by key_id with constant-time comparison; frequent failures from one address are throttled.
• CORS is not supported: calling the API directly from a browser is impossible and must not be attempted.