Authentication
Send the complete opaque token in the HTTP header:
Authorization: Bearer <api-key>Organization API Keys authenticate one Organization with no acting User. User API Keys authenticate one End User in one Organization. Console login and Organization Membership are separate management credentials.
| Operation group | Key |
|---|---|
/api/v1/org and native User/key provisioning |
Organization API Key |
Target User discovery, Sessions, Turns, Client Tools, Files, Schedulers and Realtime under /api/v1/org/users/{userId} |
Organization API Key |
Template summaries and associations under /api/v1/user |
User API Key |
| User-prefixed lifecycle; Turns, interactions, ordinary File uploads, Schedulers and Realtime Connections | User API Key |
/api/v1/connectors/ws |
Organization API Key and explicit X-Ti-Connector-Id |
/api/v1/connectors/jwks |
Public verification keys; no credential |
/api/v1/drive-downloads/{ticket}, /api/v1/drive-uploads/{ticket} |
The short-lived ticket alone |
Read the generated API reference for each operation’s security requirement. An Organization Key grants only explicitly admitted Organization operations; it does not impersonate a User. Keys have no editable per-key permission list.
Provision your application’s User
Section titled “Provision your application’s User”Keep the Organization Key in your backend. Set BASE_URL and ORGANIZATION_API_KEY, create an End User, then set USER_ID to the returned user.userId for the explicit-owner workflows. Issue a User Key only if your integration uses retained User-Key routes:
curl --fail-with-body "$BASE_URL/api/v1/org/users" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"displayName":"Application user","externalId":"app-user-001"}'
curl --fail-with-body "$BASE_URL/api/v1/org/users/$USER_ID/api-keys" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"name":"Application key"}'Save the mapping between your application identity and user.userId. externalId is unique within the Organization, and creation with it is retry-safe: the first request returns 201 with the new User, and a repeated request with exactly the same value returns 200 with the existing User unchanged, including a disabled User. A different value that equals an existing one under case- and accent-insensitive comparison, such as Ab3X against aB3x, returns 409 resource_conflict. After an uncertain User creation, repeat the same request to learn the userId. Without externalId, every request creates a new User.
Key creation returns metadata in apiKey and the secret in token. Save the token securely as USER_API_KEY. Create and rotate are secret-delivery responses; listing keys cannot recover the secret. After uncertain issuance, reconcile metadata first; a lost secret requires an explicit rotation.
List keys with GET /api/v1/org/users/{userId}/api-keys. Rotate or revoke with POST /api/v1/org/user-api-keys/{id}/rotate or /revoke. Use an effective User Key for the retained User-Key routes. Organization-Key workflows do not require one.
Provisioning creates no Platform Account, Membership or management authority. Treat tokens and upload/download links as credentials; keep them out of shared logs, URLs and source control.
Organization-Key lifecycle, text/audio Turns, Client Tools, Files/Drive, Schedulers and Realtime do not need a User Key. The selected User remains the resource owner; hidden Test and management identities are refused. Disabled ordinary Users retain supported existing-data reads, settings and cleanup. New Session creation and model-backed title suggestion require an active User. Schedulers bind their exact creating Key, including Turn-originated creation. Rotation or revocation stops future fires and preserves accepted Turns and history. A backend may automatically resume through PATCH /api/v1/org/users/{userId}/schedulers/{schedulerId} with a fresh valid Key, enabled: true and the current If-Match; use a future schedule when the one-time date expired. Old create receipts never reauthorize future work. Organization lists also accept status=deleted for retained Scheduler history. Realtime connections opened by the old credential end and their connect tokens fail; recover accepted Turn results with a valid Key and open a new connection on the same Session. Accepted Standing Turns are preserved while future cycles stop. Organization-issued file tickets reject new redemptions after invalidation, while admitted transfers may finish within their existing limits. Retained User-Key ticket lifetimes are unchanged.