Bearer depends on the caller:
The API tells access tokens and API keys apart automatically. You never label the credential type.
API clients
Server-to-server access is provisioned as API clients (machine-to-machine, or M2M, clients). Create one in the IDV Console under Settings → API clients, or withPOST /admin/m2m/clients. At creation you choose how the client authenticates:
Prefer the OAuth methods for new integrations. Short-lived tokens limit the blast radius of a leaked credential. Use an
sk-ti- API key when your platform cannot perform a token exchange.
Every client has an expires_at, with a maximum credential lifetime of 730 days, so forgotten credentials age out on their own. Creating a client requires an Owner or Admin session; see Permissions and roles.
Getting an access token
Exchange your client credentials at the token endpoint with theclient_credentials grant:
- JWTs signed with ES256; public keys are published at
GET /.well-known/jwks.json. - Short-lived: a 15-minute TTL. Fetch a fresh token when one expires; do not cache beyond
expires_in. - Audience-bound to the TruU IDV API. They are not usable elsewhere.
The token endpoint and the
/.well-known/* endpoints live at the API origin root, not under the /api/v1 base path. The exact token_endpoint URL is returned when you create the client and advertised at GET /.well-known/oauth-authorization-server (RFC 8414).sk-ti- API key in exactly the same position:
Scopes
Every API client carries a set ofallowed_scopes. Request a subset with the space-delimited scope form parameter; omit it to receive the client’s full set. Requesting a scope outside allowed_scopes returns the OAuth invalid_scope error. sk-ti- API keys always act with the client’s full allowed_scopes.
Calling an endpoint without the required scope returns
403 INSUFFICIENT_PERMISSIONS.
Console roles and scopes
Console users hold one or more roles, and the API returns aroles array everywhere:
Role capabilities are bundles of the same
idv:* scopes listed above. With Enterprise SSO, JIT grants only the Agent role. The full capability table is on Permissions and roles.
Lockout
Repeated failed authentications lock an API client for a period. While locked, API requests return429 with a Retry-After header and the error code M2M_CLIENT_LOCKED; the token endpoint returns the OAuth error temporarily_unavailable with a 429 and Retry-After. Honor Retry-After and fix the credential before retrying; retrying with the same bad credential extends the lock. API-key authentication is additionally lockout-protected per source address. Failed and denied token requests are recorded in the audit trail.
Key rotation
Rotate a client’s credential withPOST /admin/m2m/clients/{client_id}/rotate or from Settings → API clients:
- Rotation is method-aware. It issues a new secret,
sk-ti-API key, or JWK registration to match the client. - The superseded credential keeps working for a 24-hour grace window, so you can switch your integration without downtime.
- List active and grace credentials with
GET /admin/m2m/clients/{client_id}/credentials; revoke one immediately withDELETEon it. - Revoke a whole client with
DELETE /admin/m2m/clients/{client_id}.
Session tokens
Verification sessions are self-authenticating.POST /verify/start does not require an API credential; it validates the user, domain, and (for help-desk-initiated verifications) the verification request token, then returns a session_jwt:
- Bound to a single session, user, and domain. The
session_idin each request body must match the token; a mismatch returns400 SESSION_MISMATCH. - Short-lived: they expire with the session (
expires_atin the start response). - Subject to lockout. Repeated factor failures lock the user out of new sessions for a period.

