Skip to main content
This page is for the engineer wiring a system to the TruU IDV API. When you finish, you have an API client with the right scopes, a token or key in your secrets manager, and a rotation plan. The API uses bearer authentication everywhere:
What you put after 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 with POST /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.
Client secrets and API keys are returned once, in the create or rotate response, and are stored only as hashes. Save the value to a secrets manager immediately; it cannot be retrieved again.
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 the client_credentials grant:
Properties of access tokens:
  • 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).
Then call the API with the token, or with an sk-ti- API key in exactly the same position:

Scopes

Every API client carries a set of allowed_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 a roles 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 return 429 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 with POST /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 with DELETE on it.
  • Revoke a whole client with DELETE /admin/m2m/clients/{client_id}.
Client creation, rotation, and revocation are all recorded in the audit trail.
If you use the ServiceNow connector, rotating its outbound secret in TruU requires updating the matching app property in ServiceNow. Forgetting that step is the most common cause of 401 on event push. See ServiceNow.

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:
Send it on every subsequent session call:
Properties of session tokens:
  • Bound to a single session, user, and domain. The session_id in each request body must match the token; a mismatch returns 400 SESSION_MISMATCH.
  • Short-lived: they expire with the session (expires_at in the start response).
  • Subject to lockout. Repeated factor failures lock the user out of new sessions for a period.
Next, review the error reference for the token-endpoint and scope errors you should handle.