Session status - Authentica

GET {BASE}/api/V1/Verify/session/{sessionId}
Authorization: Basic {credentials}

{BASE} = https://authentica-merge-integration.t2.sa. Ask what happened to a verification. Idempotent, read-only, and safe to poll.

Why this is the whole result channel

Nothing is delivered to your server. The browser’s return to your returnUrl carries an identifier and your own state — neither proves anything — so this call is where the outcome actually comes from. It is also what makes the redirect trustworthy: because you re-read the result over an authenticated channel, a forged or replayed return URL buys an attacker nothing. Three situations all resolve here:

The normal path. The browser lands on your returnUrl; your server reads GET /session/{id} and acts on the answer.
The verification failed. The browser lands on your returnUrl exactly as it does on success — same query, nothing to distinguish the two. This call is what tells them apart. See When it fails.
The browser never came back. The user closed the tab, or lost connectivity. No redirect ever happens. A reconciliation sweep over your pending actions reads the outcome here.

Every terminal outcome is retained for 24 hours under its sessionId.

The `sessionId`

POST /session returns sessionId (for example vs_9f3c8a…). It is public and non-secret — safe to log, safe to store, safe to show on an internal admin screen. It is not a capability: reading a session requires your Basic credentials, and a session created by another client is invisible to you. Store it against the pending action at the moment you create the session, next to state.

Response

{
  "isSuccess": true,
  "statusCode": 200,
  "result": {
    "sessionId": "vs_9f3c8a…",
    "status": "verified",
    "userRef": "user-123",
    "reason": null,
    "method": "otp",
    "state": "6f1c9e2a-4b8d-4c1a-9f0e-2d3a1b5c7e8f",
    "completedAt": "2026-08-09T10:31:03.114Z",
    "assertionExchanged": false
  }
}

Field	Description
`sessionId`	Echo of the id you asked for
`status`	`pending`, `verified`, `failed`, or `expired`
`userRef`	Present only when `status` is `verified`. Exactly the string you sent on `/session`
`reason`	Present only when `status` is `failed`. Why it ended — see When it fails. `null` otherwise
`method`	How the user verified — `otp` or `passkey`
`state`	The `state` you supplied at session creation, echoed back so you can find your own record from an id alone
`completedAt`	When the session reached its terminal state
`assertionExchanged`	Legacy wire field from a removed design. It means nothing now — ignore it, and do not branch on it

`status` values

Value	Meaning	What to do
`verified`	The user completed verification	Run your idempotent `onVerified(sessionId)` — after checking `state` and `userRef` against your record
`failed`	The verification ended without success	Leave the action unperformed. Read `reason` to tell the user why
`expired`	The session ran out of time before it completed	Leave the action unperformed; start a new session if the user is still around
`pending`	No terminal outcome recorded	Keep waiting. See below

pending also covers “we have never heard of this session id”, and an id belonging to a different client_id. There is no 404 here — never treat pending as proof that a session exists. Trust your own record for that.

When it fails [#when-it-fails]

A verification that ends badly does not strand the user on our page. It sends them back to your returnUrl with the same session_id and state a successful one carries — because a user whose code locked out still needs a way back into your app, and you still need to close out the pending action rather than leave it hanging until it ages out. That means your landing route cannot assume success. Two arrivals that look identical in the URL can mean opposite things; only this endpoint distinguishes them.

The redirect carries no error code, deliberately. Anyone can craft that URL, so a ?error= in it would prove nothing — exactly as session_id alone proves nothing on the success path. status here is the authoritative answer, and reason is only ever a message to show the user.

`reason` values

Value	What happened	Reasonable response
`otp_locked`	Too many wrong codes; the attempt limit is spent	Tell the user, and offer to start over with a new session
`otp_expired`	Every code sent has expired and the resend limit is spent — no further code can arrive	Offer to start over with a new session
`device_changed`	The browser stopped matching the one that started the flow — a changed or missing device fingerprint	Treat as suspicious. Start over; if it repeats for a real user, raise it with us
`session_binding_failed`	A call arrived from a different browser than the one that opened the flow	Same as above — start over from your app, in one browser

New values may be added over time. Branch on status and treat an unrecognised reason as a generic failure rather than an error.

Handling both outcomes

GET /your/return-url?session_id=…&state=…
  ├─ look up your pending record by `state`      (unknown / used -> reject)
  ├─ GET /session/{session_id}
  ├─ status == "verified" AND state matches AND userRef matches
  │     -> onVerified(sessionId)   idempotent
  ├─ status == "failed"
  │     -> close the pending record, show `reason` to the user
  └─ status == "pending"
        -> the browser beat the result home, or the id is unknown. Keep your record; the sweep closes it

Before you act on `verified`

Three things have to agree, every time:

The state in the response equals the state on your pending record.
That record is one you created, and it is not already fulfilled.
The userRef in the response is the user you started the verification for.

Only then run fulfilment — and make it idempotent, because the landing page can be reloaded.

curl

curl "https://authentica-merge-integration.t2.sa/api/V1/Verify/session/vs_9f3c8a" \
  -u "YOUR_CLIENT_ID:YOUR_SECRET"

Errors

HTTP	errorCode	Meaning
`401`	(empty body)	Basic header missing or unparseable
`401`	`unauthorized`	Wrong `client_id` / `secret`
`400`	`missing_parameters`	No session id in the path

How to poll without being silly

Read once on the landing page

The common case is a single read: the browser arrives, you call this endpoint, you get a terminal status. No loop needed.

Back off if you do loop

A verification takes as long as a human takes to read an SMS. Poll at a few seconds, then back off; do not poll in a tight loop for the whole session lifetime.

Stop at a terminal state

verified, failed and expired never change afterwards. Stop.

Sweep the stragglers

For sessions whose browser never returned, a periodic sweep over your own pending records — one read each — closes the gap inside the 24 h window.

Create session — where sessionId comes from
API overview — the three calls, and why nothing is pushed to you

​Why this is the whole result channel

​The sessionId

​Response

​status values

​When it fails [#when-it-fails]

​reason values

​Handling both outcomes

​Before you act on verified

​curl

​Errors

​How to poll without being silly

​Related

Why this is the whole result channel

The `sessionId`

Response

`status` values

When it fails [#when-it-fails]

`reason` values

Handling both outcomes

Before you act on `verified`

curl

Errors

How to poll without being silly

Related