Skip to main content
This page is for the developer connecting a portal, chatbot, ticketing tool or script to TruU IDV. When you finish you will have sent a verification link with curl and read its result.

Before you start

  • An Owner or Admin seat, to create the API client.
  • A connected directory with at least one person you can verify (yourself is fine).
  • curl and jq.

1. Create an API client

1

Open API clients

In the console, go to Settings → API clients and choose Create client.
2

Name it and pick an auth method

Give it a Name that says what uses it, for example “Self-service portal”. Under Auth method, choose Client secret (standard OAuth 2.0 client credentials). The other options are Private key (JWT), where you register a public JWK, and Bearer token, a long-lived sk-ti- API key for platforms that can’t exchange tokens.
3

Grant only the scope you need

Under Scopes, select Run verification (idv:verification). It lets the client create verification links and read their status, and nothing else.
4

Set an expiration and create

Pick an Expiration, choose Create client, and copy the Client ID, Client secret and Token endpoint. The secret is shown once; put it in your secrets manager.

2. Get an access token

Exchange the client’s credentials for a short-lived access token (15 minutes):
Use the Token endpoint shown when you created the client if it differs. Fetch a new token when it expires rather than caching it. With a Bearer token client, skip this step and use the sk-ti- key wherever $TOKEN appears.

3. See which use cases you can send

The key is what you send as purpose. The use case decides which flow the person gets and what they’re told.
  • user_ref identifies the person by email, upn or phone; they must exist in your directory.
  • delivery_method is email or sms (sent to the contact on file), or link to get the URL back and deliver it yourself.
  • Sending again for the same person and use case returns the same request with a fresh expiry, so retries are safe.
Open the link from your inbox and complete the verification.

5. Read the result

Poll every few seconds until status is final: progress_events lists each step (factor attempts, fallbacks, the outcome) if you want to show a timeline or write a ticket note.
Gate your downstream action (password reset, account unlock) on verified only.

Next steps

  • Keep the client secret in a secrets manager and rotate it from Settings → API clients, open the client, then Rotate credential; the old credential keeps working for a grace window. See Authentication.
  • Full request and response fields: Links. Error codes: Errors.
  • Building for a help desk? The ServiceNow and Microsoft Teams connectors already do this for you.