Skip to main content

Control access with scopes

Section: DOC-CP-identity-access-scopes-permissions#control-access-with-scopes.

Build a backend that lists a signed-in person’s conversations without giving that feature a general-purpose credential. Keep privileged administration in a separate server path. This recipe uses the conversation read and impersonation permissions already documented below; add write access only if the same feature must send messages.

Choose the minimum permissions your application needs. Scopes are labels attached to an API key; where an operation enforces its scope, a missing grant returns 403 insufficient_scope. Enforcement currently varies by operation, so keep privileged calls behind your backend's access checks instead of relying on key scopes alone.

Issue the credential for the feature​

Section: DOC-CP-identity-access-scopes-permissions#where-scopes-are-set.

Scopes are set in the permissions field when a key is created or edited through the management interface enabled for your account. A valid credential can still be denied access to an operation that requires a scope it does not have.

For the conversation-list recipe, request conversations:read and users:impersonate. The example below also grants conversations:write for the optional message-sending variant; omit that grant for a feature that only lists conversations.

{
  "name": "backend-service",
  "permissions": ["conversations:read", "conversations:write", "users:impersonate"]
}

Recipe: let a person list their conversations​

Section: DOC-CP-identity-access-scopes-permissions#select-permissions-for-the-operation.

  1. List the actions the feature performs. Listing conversations needs conversations:read; a secret-key request for a person also needs users:impersonate.
  2. Request those permissions through the key-management route enabled for your account. Avoid a wildcard merely to make a denied request disappear.
  3. Resolve the user from your application’s authenticated session and call list-threads.
  4. Check a permitted request and a denied action before exposing the backend route. Keep your application’s own authorization checks because enforcement varies across APIs.
  5. If a request fails, use the denial guidance to distinguish a missing scope from a wrong or expired credential.

The result is a credential and backend route tied to a defined feature. Keys do not currently establish separate project or test/live isolation. A scope label does not validate a user ID supplied by an untrusted client.

The users:impersonate scope and X-On-Behalf-Of​

Section: DOC-CP-identity-access-scopes-permissions#the-usersimpersonate-scope-and-x-on-behalf-of.

Most platform endpoints operate on a specific user's data. When calling with a secret key (sk_*), the X-On-Behalf-Of header is how you identify that user. The key must carry the users:impersonate scope, or the request fails with 403 insufficient_scope.

If the feature also sends messages, use the same resolved user with the additional conversations:write permission. This variant requires an existing conversation key:

curl -X POST https://api.travila.ai/api/v1/llm/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "conv_abc",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Hello"
      }
    ]
  }
}'

Reference: Send a message to a conversation · Request fields.

Request this scope when you create your key. Without it, an attempt to act on behalf of a user is rejected with a 403.

For the full list of endpoints that require X-On-Behalf-Of, see Acting as a user.

Understand what a broader grant would allow​

Section: DOC-CP-identity-access-scopes-permissions#scope-matching-rules.

Keep the conversation-list feature on its named permissions. A wildcard would also permit unrelated actions as those scopes are added; use a separate credential for a feature that needs broader access. See the scope-matching reference for exact permission and wildcard behavior.

Variant: move permitted user work into a client app​

Section: DOC-CP-identity-access-scopes-permissions#publishable-key-restrictions.

Use a publishable key with the signed-in user’s JWT only for the user operations your client needs. Keep key management, billing and other administrative work on your backend; consult the publishable-key restrictions before choosing permissions.

Later key updates and operation checks do not uniformly apply this filter. Review the saved permissions after an edit, restrict who can manage keys, and keep management calls behind your backend's access checks. The user JWT accompanying a publishable key identifies the user; it does not grant permission for every operation.

Recover a denied request without widening access blindly​

Section: DOC-CP-identity-access-scopes-permissions#per-endpoint-enforcement.

A valid key and JWT do not establish permission for every operation. A request can pass authentication and still fail because the key lacks the required scope. Always check the error body for insufficient_scope rather than assuming a 401 or 403 is a credential issue.

If the error is insufficient_scope, compare the operation with the feature’s approved action list before changing the grant. If it reports expired or invalid credentials, recover authentication instead. Re-run the permitted request after the change and review the saved permissions; a successful edit is not proof that every operation enforces the intended restriction.

Section: DOC-CP-identity-access-scopes-permissions#related.

Document ID: DOC-CP-identity-access-scopes-permissions. Section identities and revisions.