Create session - Authentica

POST {BASE}/api/V1/Verify/session
Authorization: Basic {credentials}
Content-Type: application/json
Idempotency-Key: 8b7d2e0a-…   (optional, recommended)

{BASE} = https://authentica-merge-integration.t2.sa.

Request body

Field	Type	Required	Description
`userRef`	string	yes	Stable id for this user in your system (same value every time, for every action)
`destination`	string	yes	Phone number, E.164 preferred (e.g. `0501234567`). The hosted UI does not ask for it
`channel`	string	yes	`"sms"` — the only accepted value
`state`	string	yes	An opaque value you generate and store against the pending action. Echoed back on the return URL and on `GET /session/{id}` — it is how you know which action completed
`returnUrl`	string	yes	Where verification returns when it finishes, always carrying `?session_id=…&state=…`. For `web` an ordinary `http`/`https` page in your app, reached with a plain `GET`; for `mobile` it may instead be a registered custom-scheme deep link (`myapp://…`). Must be registered for this client, matched as a whole string
`operationSensitivity`	string	no	Chosen by your backend: `"normal"` (default) or `"sensitive"` — sensitive forces OTP even when a passkey exists. Never take this from the browser
`platform`	string	no	Chosen by your backend per session: `"web"` (default) or `"mobile"`. `"web"` requires an `http`/`https` `returnUrl`; `"mobile"` also allows a registered custom-scheme deep link (`myapp://…`) so the OS can route the return into your native app. Either way the return carries `?session_id=&state=`. A browser can’t choose it — it rides on the authenticated `/session` call
`nonce`	string	no	Your own optional value for the session. One is generated if you omit it

You register exactly one URL for the app: returnUrl, the GET landing page. There is no second URL to register — nothing is delivered to your server, so there is no receiver to point at. See Get your credentials.

`returnUrl` is matched as a whole string

Registration is an exact, case-sensitive, whole-string comparison against the URLs on your app. Not a prefix match, not a host match:

no trailing slash unless the registered value has one
no query string appended
http vs https, www vs bare host, and localhost ports all matter

Any mismatch fails the session create with invalid_return_url — the browser never leaves your app, so this shows up in your own logs, not the user’s.

Channel (`sms` only)

OTP is delivered by SMS to a phone number:

Field	Value
`channel`	`"sms"`
`destination`	Phone, e.g. `0501234567`

Any other value → invalid_channel. A missing or unusable destination → destination_required.

Operation sensitivity

How risky the action behind this session is. Set by your backend when creating the session:

Value	Behavior	Typical actions
`"normal"`	Default. A passkey may replace OTP when the user has one enrolled	Login, viewing protected data, low-risk confirmations
`"sensitive"`	Always SMS OTP — no passkey shortcut	Payments and transfers, adding a beneficiary, changing phone or email, permission changes, account closure

Sensitivity is per session, so the same integration can use "normal" on one route and "sensitive" on another. Anything other than those two values → invalid_operation_sensitivity.

Example

{
  "userRef": "user-123",
  "destination": "0501234567",
  "channel": "sms",
  "state": "6f1c9e2a-4b8d-4c1a-9f0e-2d3a1b5c7e8f",
  "returnUrl": "https://yourapp.com/verify/done",
  "operationSensitivity": "normal"
}

curl

curl -X POST "https://authentica-merge-integration.t2.sa/api/V1/Verify/session" \
  -u "YOUR_CLIENT_ID:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"userRef\": \"user-123\",
    \"destination\": \"0501234567\",
    \"channel\": \"sms\",
    \"state\": \"random-value\",
    \"returnUrl\": \"https://yourapp.com/verify/done\",
    \"operationSensitivity\": \"normal\"
  }"

Idempotency

POST /session is the call your HTTP client retries on timeout, and the one that costs money in SMS — so a retry must not text the user twice. Send an optional Idempotency-Key header (any unique string per logical attempt, up to 255 characters), following the IETF Idempotency-Key draft:

Situation	Result
Same key, same payload, original succeeded	The stored response is replayed, with `Idempotent-Replayed: true` on the response
Same key, different payload	`422` with `errorCode: "idempotency_key_reused"`
Same key while the original is still running	`409` with `errorCode: "idempotency_request_in_flight"`
Key longer than 255 characters	`400` with `errorCode: "idempotency_key_too_long"`

Only a successful response is stored for replay — a failure is retryable as normal. Keys are retained for 24 hours and are scoped to your client_id.

# Safe to run twice: the second call replays the first response instead of sending a second SMS.
curl -X POST "https://authentica-merge-integration.t2.sa/api/V1/Verify/session" \
  -u "YOUR_CLIENT_ID:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-8842-attempt-1" \
  -d '{ … }'

Do not reuse one key for two different attempts. “Retry of the same attempt” gets the same key; “the user pressed send again” gets a new one — otherwise the second attempt either replays a stale response or fails with 422.

Success response

HTTP 200, isSuccess: true:

{
  "isSuccess": true,
  "statusCode": 200,
  "result": {
    "sessionId": "vs_9f3c8a…",
    "verifyUrl": "https://otp.t2.sa/verify",
    "handoff": "9f3c…",
    "handoffField": "hx",
    "binding": "form_post",
    "expiresInSeconds": 120,
    "renderType": "redirect"
  }
}

Field	Description
`sessionId`	Public, non-secret id for this verification. Store it against the pending action: it is how you read the outcome with `GET /session/{sessionId}`
`verifyUrl`	Bare hosted verify endpoint — no query string. You `POST` the hand-off token to it
`handoff`	Single-use hand-off token. Send it as a hidden form field. Never put it in a URL
`handoffField`	Name of the form field to submit `handoff` under. Currently `"hx"` — read it from the response instead of hard-coding it
`binding`	How the browser opens the hosted page. Always `"form_post"`. This describes the outbound leg only — the return leg is a plain GET
`expiresInSeconds`	Lifetime of `handoff`, in seconds. Currently `120`
`renderType`	Always `"redirect"` — the hosted page is a full top-level page. It refuses to be framed (`frame-ancestors 'none'`), so there is no inline or iframe presentation

The `handoff` token

handoff is the capability that opens the hosted verify page. It is:

Single-use — redeemed the first time it is POSTed to verifyUrl. A replay returns 400.
Short-lived — TTL expiresInSeconds (120 s today). Create the session at the moment the user is ready to verify, not minutes ahead.
URL-forbidden — it must only ever travel in a request body. GET {verifyUrl} with any query string is rejected with 400.

Pass verifyUrl and handoff down to the browser together, and hand off with an auto-submitting form — see Frontend overview.

Client platform (`web` / `mobile`)

platform tells Authentica which kind of client finishes the flow. Your backend sets it per session — a browser cannot choose it, because it rides on the authenticated POST /session call. It only changes which returnUrl schemes are accepted; the return itself is unchanged.

Value	`returnUrl` it accepts	Where the return lands
`"web"` (default)	`http`/`https` only	The browser lands on your page; you read the outcome with an authenticated `GET /session/{id}`
`"mobile"`	`http`/`https` or a registered custom-scheme deep link (`myapp://…`)	The OS routes the deep link to your native app, which reads `session_id`/`state` and calls your backend

Either way the return carries the same ?session_id=…&state=…; only the accepted returnUrl schemes differ. A mobile return is just that same ?session_id=&state= appended to your registered deep link. For the full mobile integration, see Mobile apps.

Common errors

errorCode	HTTP	Meaning
`unauthorized`	401	Bad client id / secret
`missing_parameters`	400	`userRef`, `state` or `returnUrl` missing
`destination_required`	400	`destination` missing or not a usable phone number
`invalid_return_url`	400	`returnUrl` does not exactly match a registered URL for this client
`invalid_channel`	400	Channel is not `"sms"`
`invalid_operation_sensitivity`	400	`operationSensitivity` is not `"normal"` or `"sensitive"`
`idempotency_key_too_long`	400	`Idempotency-Key` over 255 characters
`idempotency_key_reused`	422	Same key, different payload
`idempotency_request_in_flight`	409	Same key while the original request is still running

What to do with the response

Store sessionId next to state on the pending action, along with what the action actually is.
Return verifyUrl and handoff — and nothing else — to your frontend:

{ "verifyUrl": "https://otp.t2.sa/verify", "handoff": "9f3c…" }

The browser POSTs the token into the hosted page. When the user comes back, your landing page reads the outcome with GET /session/{sessionId}.

Where to call this

Only from your backend, inside whichever route owns the action your frontend triggered — /verify/start, /payments/confirm, /profile/change-phone, and so on.

​Request body

​returnUrl is matched as a whole string

​Channel (sms only)

​Operation sensitivity

​Example

​curl

​Idempotency

​Success response

​The handoff token

​Client platform (web / mobile)

​Common errors

​What to do with the response

​Where to call this

Request body

`returnUrl` is matched as a whole string

Channel (`sms` only)

Operation sensitivity

Example

curl

Idempotency

Success response

The `handoff` token

Client platform (`web` / `mobile`)

Common errors

What to do with the response

Where to call this