Skip to content

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.

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:

Terminal window
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.