> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate to the TruU IDV API with OAuth 2.0 client credentials (ES256 tokens, 15 minutes), sk-ti- API keys, or verification session tokens. API clients, the scope list, lockout, and key rotation with a 24-hour grace window.

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:

```bash theme={null}
Authorization: Bearer <credential>
```

What you put after `Bearer` depends on the caller:

| Credential | Used for | Where it comes from |
| - | - | - |
| **OAuth access token** (short-lived JWT) | Server-to-server calls, per scope | `POST /oauth/token`, using an API client's credentials |
| **API key** (`sk-ti-...`) | Server-to-server calls, per scope | Issued once when you create an API client with the `bearer_token` method |
| **Session token** (JWT) | `/verify/*` calls after `start` | Returned by `POST /verify/start` |

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:

| Auth method | How it authenticates |
| - | - |
| `client_secret_basic` | Exchanges a client ID and secret at `POST /oauth/token` for a short-lived access token |
| `private_key_jwt` | Exchanges a signed JWT assertion (RFC 7523) at `POST /oauth/token`; you register a public JWK and sign with ES256 or RS256 |
| `bearer_token` | Sends a long-lived `sk-ti-` API key directly on every request, with no token exchange |

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.

> [!WARNING]
>
> 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](https://docs.truu.ai/idv/admin/team-and-roles.md).

## Getting an access token

Exchange your client credentials at the token endpoint with the `client_credentials` grant:

```bash curl theme={null}
curl -X POST "https://agent.truu.ai/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=idv:verification idv:audit:read"
```

```python Python theme={null}
import httpx



resp = httpx.post(
    "https://agent.truu.ai/oauth/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "client_credentials",
        "scope": "idv:verification idv:audit:read",
    },
)
resp.raise_for_status()
access_token = resp.json()["access_token"]
```

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.

> [!NOTE]
>
> 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:

```bash curl theme={null}
# With a short-lived access token
curl "https://agent.truu.ai/api/v1/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# With a long-lived sk-ti- API key (bearer_token clients)
curl "https://agent.truu.ai/api/v1/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35" \
  -H "Authorization: Bearer $TRUU_API_KEY"
```

```python Python theme={null}
import httpx

BASE = "https://agent.truu.ai/api/v1"

# With a short-lived access token
resp = httpx.get(
    f"{BASE}/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35",
    headers={"Authorization": f"Bearer {access_token}"},
)

# With a long-lived sk-ti- API key (bearer_token clients)
resp = httpx.get(
    f"{BASE}/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35",
    headers={"Authorization": f"Bearer {TRUU_API_KEY}"},
)
```

## 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`.

| Scope | Grants |
| - | - |
| `idv:verification` | Create verification links and requests, read their status (the only scope the ServiceNow app holds) |
| `idv:factor:read`, `idv:factor:manage` | Read or configure factor definitions |
| `idv:flow:read`, `idv:flow:manage` | Read or edit flows, templates, versions |
| `idv:policy:read`, `idv:policy:manage` | Read or manage use cases. Shown in the console as **Read use cases** and **Manage use cases**; the scope names predate use cases. |
| `idv:directory:read`, `idv:directory:manage` | Inspect or connect, rotate, rediscover, disconnect the directory |
| `idv:storage:manage` | Connect and configure your own storage and encryption |
| `idv:audit:read`, `idv:audit:export` | Query or export the audit trail |
| `idv:credential_health:read`, `idv:credential_health:sync` | Read connector health; trigger a refresh |
| `idv:dashboard:read` | Insights data |
| `idv:team:read`, `idv:team:manage` | Console team membership and roles |
| `idv:sso:manage` | Configure console SSO |
| `idv:m2m:admin`, `idv:domain:manage` | Administrative; available to Owner and Admin sessions, never to API clients |
| `idv:domain:delete`, `idv:sso:recovery:manage` | Administrative; available to Owner sessions only, never to API clients |

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 | Capability bundle | Signs in to |
| - | - | - |
| **Owner** | Everything, including SSO recovery and workspace deletion | IDV Console, help desk app |
| **Admin** | Configuration, connectors, storage, directory, team, Security, API clients, audit | IDV Console, help desk app |
| **Agent** | Create and watch verification requests | help desk app |

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](https://docs.truu.ai/idv/admin/team-and-roles.md).

## 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.

> [!TIP]
>
> 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](https://docs.truu.ai/idv/connect/servicenow.md).

## 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`:

```json theme={null}
{
  "session_id": "8b6a2f0e-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
  "session_jwt": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-06-09T18:30:00Z"
}
```

Send it on every subsequent session call:

```bash theme={null}
curl -X POST "https://agent.truu.ai/api/v1/verify/execute" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "...", "column_id": "...", "factor_definition_id": "...", "payload": {"code": "482913"}}'
```

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](https://docs.truu.ai/idv/api/errors.md) for the token-endpoint and scope errors you should handle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.