Connect signed-in users to their conversations

Section: DOC-CP-identity-access-authentication#authentication--api-keys.

Let a person sign in to your application and reopen their saved conversations. This recipe has your backend request that person’s conversation list and return it to the application. Keep the secret key on the server; derive the user from the session your application has already authenticated.

Before you start

Section: DOC-CP-identity-access-authentication#choose-your-integration.

Have your application’s sign-in flow, the account and API origin supplied by your administrator, and one controlled application user. Ask the administrator to issue a secret key with conversations:read and users:impersonate for this feature. Copy the key when it is created: its full value is shown once.

Use the key-management route enabled for your account. The current public reference publishes no application key-management endpoint. A console session is separate from application authentication, and naming a key after a project or “test” does not create isolation.

Keep this request in the backend unless your feature specifically needs the direct browser/mobile variant.

Show the signed-in person’s conversations

Section: DOC-CP-identity-access-authentication#1-backend-with-a-secret-key.

1. Store the issued secret key in your backend’s secret configuration. Keep it out of client code and shared request logs.
2. Resolve the person’s Travila user ID from your authenticated application session. Do not trust a user ID sent by a browser merely because your backend can impersonate users.
3. Call list-threads with that key and user. Replace user_123 with the resolved identity and use your account’s API origin:

curl -X POST https://api.travila.ai/api/v1/llm/list-threads \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Reference: List conversation threads · Request fields.

4. Read the result using the list-threads response schema and show those conversations in your application. An empty list is a valid result for a new user.
5. Reopen the list as the same person and confirm it contains their expected conversations. Test another controlled user through the same application route so a cached response cannot show the first person’s work.

The completed feature ties each displayed conversation list to the signed-in person. A successful request proves access for this operation, not that all other features are enabled. Continue with the chat recipe when the person must open a conversation and send another message; that feature also needs write permission.

Recover a rejected request

Section: DOC-CP-identity-access-authentication#error-responses-and-troubleshooting.

Read the error before replacing a credential or widening access:

What failed	Recovery
authenticated user_id is required	Supply the user resolved from your application session in X-On-Behalf-Of. The secret key identifies the tenant, not the person.
insufficient_scope	Check the feature’s approved read and impersonation grants with the administrator. Do not add a wildcard to make the request pass.
Missing, expired, disabled or revoked key	Use the key error reference to correct the key or obtain its replacement. A revoked key cannot be restored.
429 or a temporary verification failure	Use bounded backoff and any returned retry guidance within your request deadline; stop and surface the failure when that deadline expires.

Retry the list read after resolving the identified problem. Keep application authorization checks: scope enforcement varies by operation. The accepted per-minute limit is not a guaranteed traffic or spending ceiling; hourly and burst settings are unsupported. Use the current limit and error reference when configuring production traffic.

Variant: load the list directly in a browser or mobile app

Section: DOC-CP-identity-access-authentication#2-client-app-with-a-publishable-key.

Use this variant when the client must call Travila directly. It uses a publishable key and the signed-in user’s token; the server secret never ships to the client.

1. Have the administrator configure a publishable key for the accepted identity provider, issuer and audience using the identity configuration reference. The current provider allowlist does not accept Keycloak or arbitrary custom-JWKS providers.
2. Sign the person in through that configured provider and obtain its accepted user token.
3. Request the conversation list with both credentials:

curl -X POST https://api.travila.ai/api/v1/llm/list-threads \
  -H "X-API-Key: pk_your_key_here" \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Reference: List conversation threads · Request fields.

4. Display the returned list for that session. If the token expired, refresh it through the sign-in provider; for issuer, audience or signature errors, correct the configured identity path using the token error reference.

The user comes from the validated token, so this path does not use X-On-Behalf-Of. Keep management actions on your backend: publishable-key creation filters do not uniformly apply to later key edits and operation checks. Review saved permissions using the restriction reference.

Replace a backend key while the application keeps working

Section: DOC-CP-identity-access-authentication#key-rotation.

For a planned replacement:

1. Issue the successor through the key-management route enabled for your account. Record the application and consumers that must switch.
2. Update each consumer’s secure configuration and run the permitted conversation-list request with the new key.
3. Confirm every consumer has switched, then revoke the predecessor or let its chosen grace period expire.

The current rotation contract defaults to a 24-hour overlap and allows up to 720 hours. Revocation may not stop requests already in flight or immediately reach every cache. For suspected exposure, revoke the exposed credential promptly and recover its consumers.

Publishable keys use a different replacement path: issue a new key, migrate clients, then revoke the old one. See the replacement contract for those limits and the authentication reference for the remaining shared configuration details.

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