Auvral Docs

Create a verification session

POST/v1/sessions

Creates a verification session for one of your users and returns the URL they must open.

Call this from your backend. The x-api-key header is a secret and must never reach a browser.

The returned url is for one person and expires quickly, within minutes, and always before the session itself. Create the session at the moment you are about to show it, rather than ahead of time, and do not forward it, share it or reuse it for a second user.

The URL can be opened two ways:

Embedded, by passing it to AuvralVerification.init({ url }) from the web SDK. This is the usual integration.
As a plain link (a redirect, a button, an email). Set returnUrl so the user has somewhere to go when they finish.

The URL belongs to whoever opens it first; a second person opening the same link is turned away. Your own user may reopen it as often as they need (a refresh, a closed tab) and resumes where they stopped.

This endpoint always creates a new session. referenceId is your own identifier for the person and is never treated as an idempotency key: calling twice with the same referenceId gives you two independent sessions, both attached to the same identity in your dashboard.

Authorization

ApiKeyAuth

x-api-key<token>

Your organization's secret key, sk_auvral_test_… in sandbox or sk_auvral_live_… in live. Server-side only.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

flowId*string

The verification flow to run, configured in the Auvral dashboard. Editing a flow does not change sessions you have already created.

Must belong to the same organization as the API key, otherwise 404.

Formatuuid

referenceId?string

Your own identifier for the person, typically your user's id. Auvral stores it, echoes it back in every response and every webhook, and never interprets it.

It identifies a person, not a call, so send the same value every time you verify the same person: your dashboard groups all of their verifications, across flows, under one identity. It is not an idempotency key, and two sessions with the same referenceId are two independent sessions.

Optional. When you omit it Auvral assigns a uuidv7 and returns it, and your dashboard shows that identity as "Assigned by Auvral" so you can correct it by hand later. Always send your own if you have one: an assigned reference is a person you cannot look up.

Leading and trailing whitespace is trimmed; the result must be non-empty and at most 128 characters. Anything else is 400 INVALID_REFERENCE_ID, or 400 REFERENCE_ID_TOO_LONG when it is too long.

Unique per organization and environment: the same value in sandbox and in live are two different people, deliberately, so your sandbox tests never attach to a live identity.

Length1 <= length <= 128

metadata?

Your own key-value pairs, carried with this verification and given back unchanged by both reads and every webhook. Auvral never interprets them.

Flat strings only, within these limits:

Limit	Value
keys	at most 50
key length	1 to 40 characters
value type	string, and only string
value length	at most 500 characters
nesting	none; an object or an array as a value is refused

Anything outside them is 400 INVALID_METADATA, with a message naming the rule that failed. Omitted reads back as null; {} reads back as {}.

It belongs to this verification, not to the person, so two verifications of the same referenceId may carry different metadata. It cannot be changed after the session is created.

Do not put anything secret in it: it is echoed to your webhook endpoints.

expiresIn?integer

How long the session stays usable, in seconds. Defaults to one hour, maximum 24 hours. Must be a positive integer.

This is the budget for the whole verification, including your user fetching their ID or moving to their phone. Raise it if your users are likely to be interrupted. It is not the lifetime of the url, which is shorter.

Formatint32

Range1 <= value <= 86400

Default3600

allowedOrigins?array<>

Origins allowed to receive the browser-side result message when the flow is embedded in an iframe. An origin is a scheme + host + port and nothing else: https://app.example.com, not https://app.example.com/onboarding.

Every entry is validated, and a malformed one is a 400 (INVALID_ALLOWED_ORIGINS) naming the entry and the canonical form that would have been accepted. An entry must be either "*" or an http/https origin with no path, query, fragment or trailing slash. partner.com (no scheme), https://partner.com/ (trailing slash) and HTTPS://Partner.COM (not lowercase) are all rejected rather than quietly corrected, because a list that was corrected behind your back is a list you never learn is wrong. The default port may be spelled out: https://app.example.com:443 is accepted and stored as https://app.example.com. Duplicates are collapsed. At most 20 entries, each at most 255 characters.

Optional here, effectively required for any embedded integration. The verification flow sends its result only to an origin on this list, and an absent field means an empty list, so nothing matches. The SDK's onResult and onClose then never fire, with no error, nothing in the console and nothing on the network.

Omit it only when you open the URL as a plain link rather than embedding it.

["*"] is the deliberate opt-out: the flow posts its result to whatever page embeds it, for the case where the embedding origin cannot be known when the session is created. It cannot be combined with a concrete origin: ["*", "https://app.example.com"] is a 400, since the two ask for opposite things. Send one or the other.

The message these origins receive is a UI signal, not proof. Never change business state from it: the webhook is the only authoritative signal that a verification finished.

Itemsitems <= 20

Default[]

returnUrl?string

Where to send your user when they finish, for the standalone link flow. Ignored when the flow is embedded with the SDK, where the final button closes the overlay instead.

Must be an absolute http or https URL, at most 2048 characters; anything else is a 400 (INVALID_RETURN_URL). A relative path (/done), a host with no scheme (app.example.com) and any other scheme, javascript: and data: in particular, are all rejected. Unlike allowedOrigins this is a destination rather than an origin, so a path and a query are expected and are stored exactly as you sent them.

With no returnUrl and no embedding, the final screen has no button.

Formaturi

Lengthlength <= 2048

flowVersion?string

Which version of the flow to run.

published is the version your dashboard shows as published, and the only one a live key may run. A flow that has never been published has none, so asking for it returns 409 FLOW_NOT_PUBLISHED.

draft runs the flow's unpublished changes and is accepted only with a sandbox key; a live key asking for it gets 400 DRAFT_REQUIRES_SANDBOX_KEY. It is how you try an edit end to end before publishing it. A flow with no unpublished changes has no draft, so asking for it returns 404 FLOW_DRAFT_NOT_FOUND.

Any other value is 400 INVALID_FLOW_VERSION.

The session pins the version it opened on: publishing, editing or discarding afterwards never changes what a session already created runs.

Default"published"

Value in

"published"
"draft"

locale?string

Language the verification flow is shown in. en and es are supported, and a BCP 47 tag is accepted: only its language subtag is read, so en-US is en and es-PE is es.

Omitted or unsupported is not an error: the flow then follows the person's browser language, and falls back to es.

providedDetails?

Details you already hold about the user, so they are not asked for them again.

Response Body

`application/json`

curl -X POST "https://example.com/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "flowId": "3f1c9a52-4d7e-4b3a-9c21-8e5f6a0b7d34",    "referenceId": "user_8842"  }'

{  "statusCode": 201,  "data": {    "sessionId": "9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047",    "url": "https://verify.example.com/c/Jk3nQ7pXsR2vLm9Ab4Cd1e?locale=en",    "expiresAt": "2026-08-25T15:42:11.084Z",    "referenceId": "user_8842",    "metadata": {      "orderId": "order-8841"    }  }}

Read a session

GET/v1/sessions/{sessionId}

Returns where a session got to, as the server sees it. This is what your own backend should trust when it needs to know an outcome and the webhook is not there.

Webhooks stay authoritative; this is how you reconcile. Call it when a delivery is missing, when a nightly sweep finds a session you never heard back about, or when support asks about one user. Do not call it in a loop while a verification runs: nothing arrives sooner because you asked, and the browser-side signal is not proof either.

Sessions are short-lived. Once one has expired and been swept, the answer is rebuilt from the verification it produced, so a session that got as far as your user starting it keeps answering long after the session itself is gone. A session that expired without ever being started leaves nothing behind and answers 404.

The response carries no personal data, no document contents, no device information and no session credential. It is a status, not the verification record; for the verification itself use GET /v1/verifications/{id} below.

Authorization

ApiKeyAuth

x-api-key<token>

Your organization's secret key, sk_auvral_test_… in sandbox or sk_auvral_live_… in live. Server-side only.

In: header

Path Parameters

sessionId*string

The sessionId you were given when you created the session.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v1/sessions/9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047"

{  "statusCode": 200,  "data": {    "sessionId": "9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047",    "status": "collecting",    "submitted": false,    "closed": false,    "verificationId": null,    "result": null,    "referenceId": "user_8842",    "metadata": {      "orderId": "order-8841"    },    "createdAt": "2026-08-25T14:42:11.084Z",    "expiresAt": "2026-08-25T15:42:11.084Z"  }}

Read a verification

GET/v1/verifications/{id}

Returns one verification of your organization: its status, the session it came from, your own referenceId and metadata, and when it started and ended.

Use it to reconcile, the same way as the session read: after a webhook you cannot account for, or when you hold a verificationId from an earlier event and want the server's current answer. It is not a progress feed, and polling it while the checks run tells you nothing a webhook will not tell you sooner.

The response is an allow-list. The identity behind the verification, the flow version it ran, the step it is on and the checks it made are not part of this contract: they are in your dashboard, where a person can look at them.

Authorization

ApiKeyAuth

x-api-key<token>

Your organization's secret key, sk_auvral_test_… in sandbox or sk_auvral_live_… in live. Server-side only.

In: header

Path Parameters

id*string

The verificationId, which arrives in every verification webhook and in the session read once your user has started.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v1/verifications/6d1a7f34-5b28-4c90-8e13-9f2a4c7b0e56"

{  "statusCode": 200,  "data": {    "verificationId": "6d1a7f34-5b28-4c90-8e13-9f2a4c7b0e56",    "status": "VERIFIED",    "sessionId": "9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047",    "referenceId": "user_8842",    "metadata": {      "orderId": "order-8841"    },    "flowId": "3f1c9a52-4d7e-4b3a-9c21-8e5f6a0b7d34",    "environment": "SANDBOX",    "startedAt": "2026-08-25T14:43:02.512Z",    "endedAt": "2026-08-25T14:47:39.310Z"  }}

API reference

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

401application/json

404application/json

500application/json

Your user is still in the flow

Finished, and it passed

Rebuilt from the verification, after the session was swept

200application/json

401application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`