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).
curlandjq.
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):sk-ti- key wherever $TOKEN appears.
3. See which use cases you can send
key is what you send as purpose. The use case decides which flow the person gets and what they’re told.
4. Create a verification link
user_refidentifies the person byemail,upnorphone; they must exist in your directory.delivery_methodisemailorsms(sent to the contact on file), orlinkto 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.
5. Read the result
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.
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.

