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

# API Overview

> Programmatic access to TruU IDV: verification requests, sessions, configuration, directory, and audit. Base URL, scopes, lifecycle, and limits.

The TruU IDV API gives you programmatic access to everything the IDV Console and help desk app can do: create and deliver verification links, track requests, run verification sessions, manage factors and flows, connect a directory, and read or export the audit trail.

## What you can build

> [card] [Automate configuration](https://docs.truu.ai/idv/api/authentication.md)
>
> Manage factor definitions and flows from scripts or CI for bulk configuration and migration between environments.

> [card] [Consume verification results](https://docs.truu.ai/idv/api/quickstart.md)
>
> Poll request status, update tickets, gate downstream automation on a `verified` outcome, and pull audit evidence into your SIEM through the export API.

> [card] [Create verification links from your systems](https://docs.truu.ai/idv/api/links.md)
>
> One call to `POST /integrations/links` creates a request, delivers the link, and returns the URL and expiry. This is the endpoint the ServiceNow app uses, and the fastest way to wire verification into any ITSM or portal.

> [card] [Build a custom verification surface](https://docs.truu.ai/idv/api/authentication.md)
>
> Use the session APIs (`/verify/start`, `/verify/execute`, `/verify/complete`) to embed verification in your own application instead of the hosted page.

## Base URL

All endpoints in the reference are relative to your workspace's API base URL:

```text theme={null}
https://agent.truu.ai/api/v1
```

> [!NOTE]
>
> OAuth and discovery endpoints (`/oauth/token`, `/.well-known/*`) live at the API origin root, above the `/api/v1` base path.

## API groups

| Group | What it covers |
| - | - |
| Partner Links | Create a verification link for a user with a single call (`POST /integrations/links`) and list the flows available to the caller (`GET /integrations/flows`). See [Links](https://docs.truu.ai/idv/api/links.md). |
| Verification Requests | Create, list, and get verification requests; per-request progress timeline; cancel. |
| Help Desk Users | Directory user search and contact lookup for request creation. |
| Verification Sessions | Start a session, execute factors, report fallback events, complete; token resolution for the hosted verification page. |
| Factors | List, inspect, enable/disable, and configure factor definitions. |
| Flows | Flow CRUD, suggested templates, risk assessment, and version history. |
| Directory | Connect (Entra ID), inspect, rotate, rediscover, and disconnect the directory connection; attribute mapping. |
| Audit Events | Query and export the tenant-scoped audit trail. |
| M2M Clients | Create, list, rotate, and revoke the OAuth clients and API keys that authenticate your integrations. |
| Storage | Connect and read your own cloud storage configuration for verification assets. |
| Credential Health | Read connector and credential health; trigger a refresh sync. |
| Integrations | ServiceNow, Windows TAP, PingOne, and Passwordless connector administration and linking codes. |

The complete endpoint reference is generated from the OpenAPI specification and appears in the navigation alongside these guides.

## A typical integration

```bash curl theme={null}
# 1. Create and deliver a verification link
curl -X POST "https://agent.truu.ai/api/v1/integrations/links" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ref": { "email": "nsharma@contoso.com" },
    "purpose": "helpdesk",
    "delivery_method": "sms",
    "context": { "ticket": "INC0012345" }
  }'

# 2. Poll until the request reaches a final state
curl "https://agent.truu.ai/api/v1/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

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

import httpx

BASE = "https://agent.truu.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

# 1. Create and deliver a verification link
resp = httpx.post(
    f"{BASE}/integrations/links",
    headers=HEADERS,
    json={
        "user_ref": {"email": "nsharma@contoso.com"},
        "purpose": "helpdesk",
        "delivery_method": "sms",
        "context": {"ticket": "INC0012345"},
    },
)
resp.raise_for_status()
request_id = resp.json()["request_id"]

# 2. Poll until the request reaches a final state
FINAL = {"verified", "expired", "failed", "cancelled", "declined"}
while True:
    req = httpx.get(f"{BASE}/helpdesk/requests/{request_id}", headers=HEADERS).json()
    if req["status"] in FINAL:
        break
    time.sleep(3)

print(req["status"])  # "verified" on success
```

Verification requests move through a fixed lifecycle:

```text theme={null}
pending → in_progress → (needs_review →) verified | failed | expired | cancelled | declined
```

`verified`, `failed`, `expired`, `cancelled`, and `declined` are terminal. The `progress_events` array on the request records each step (preflight skips, factor successes and failures, fallbacks, and the final outcome), so you can render a timeline or write work notes from a single GET.

## Versioning

The API is versioned in the URL path (`/v1`). Within a version, changes are backwards-compatible: new fields, new endpoints, and new enum values may be added, but existing fields are not renamed or removed. Build clients that ignore unknown fields.

## Authentication

Server-to-server calls authenticate with OAuth 2.0 client credentials (ES256-signed access tokens valid for 15 minutes) or a long-lived `sk-ti-` API key. You create an M2M client in the IDV Console (under **Settings → API clients**), then either exchange its credentials at `POST /oauth/token` for a short-lived access token or send a long-lived `sk-ti-` API key directly. Each client carries `idv:*` scopes that gate what it can call. Verification session calls use the session token returned by `start`.

The complete scope list:

| 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 as **Read use cases** and **Manage use cases**; legacy names) |
| `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 machine clients |
| `idv:domain:delete`, `idv:sso:recovery:manage` | Administrative; available to Owner sessions only, never to machine clients |

See [Authentication](https://docs.truu.ai/idv/api/authentication.md) for clients, scopes, and rotation.

## Rate limiting

Requests that return `429` carry a `Retry-After` header; honor it before retrying. Repeated failed authentications temporarily lock the client (error code `M2M_CLIENT_LOCKED`). API keys have a maximum lifetime and a short grace window after rotation; see [Authentication](https://docs.truu.ai/idv/api/authentication.md).

## Errors

All errors share a single JSON envelope with a stable `code`, a human-readable `message`, and optional `details`. See [Errors](https://docs.truu.ai/idv/api/errors.md) for the full status code and error code reference.

> [!NOTE]
>
> Outbound webhooks are not available. Poll request status as shown above, or use the [ServiceNow connector](https://docs.truu.ai/idv/connect/servicenow.md), which pushes lifecycle events to your instance.


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