Create a hosted session

POST /sessions · Hosted · version 2026-09-14

The whole reading, on a screen we host. You need an API key and a redirect — no SDK, no camera code, no proof handling.

Create the session, send the person to url, and read the outcome from the webhook or from the return_url callback. The proof never touches your frontend.

One session does one thing. mode decides which: claim a person, recognise one, ask for an attribute, or take a mandate grant.

Base URL

https://api.sidaxis.com/v1 in production, https://sandbox.api.sidaxis.com/v1 in sandbox.

Parameters

Name	In	Type	Required	Description
Authorization	header	string	required	Bearer sk_live_… in production, sk_test_… in sandbox.
Sidaxis-Version	header	string	optional	Dated version. Pin it in production.
Idempotency-Key	header	string	optional	Replaying a key returns the original session and its url instead of opening a second one.

Request body

Field	Type	Required	Description
mode	enum	required	What the session is for. Each maps to the headless endpoint of the same name.
return_url	string	required	Where the person lands when the session ends. Sidaxis appends session_id and status; read the result from the API or the webhook, never from the query string alone.
cancel_url	string	optional	Where a person who abandons the session lands. Defaults to return_url.
facetoken	string	optional	Required for mode recognise, attribute and mandate. Who the session is about.
attribute	enum	optional	Required for mode attribute. The single predicate you are asking for.
mandate	object	optional	Required for mode mandate. The same five fields as POST /mandates, minus granted_by — the session proves who is granting.
branding	object	optional	White-label: logo_url, accent, domain, headline, footer_note. Included in the free tier.
locale	string	optional	BCP 47. Defaults to the person's browser.
metadata	object	optional	Your own strings, returned unchanged on the session and the webhook.

Example request

{
  "mode": "mandate",
  "return_url": "https://acme.example/agent/setup/done",
  "facetoken": "0xA1f3c9b27d04",
  "mandate": {
    "granted_to": "agent_7f2c",
    "scope": [
      "payment"
    ],
    "ceiling": {
      "amount": 200,
      "currency": "USD",
      "period": "month"
    },
    "until": "2027-03-01T00:00:00Z"
  },
  "branding": {
    "logo_url": "https://acme.example/logo.svg",
    "accent": "#2DD48F",
    "domain": "id.acme.example",
    "headline": "Authorise your assistant"
  }
}

Responses

201 — Session open

Redirect the person to url. It is single-use and expires.

{
  "id": "ses_2a91c4f7",
  "status": "open",
  "mode": "mandate",
  "url": "https://id.acme.example/s/2a91c4f7",
  "expires_at": "2026-09-14T11:34:02Z",
  "created_at": "2026-09-14T11:04:02Z",
  "metadata": {}
}

Errors

invalid_return_url, allowance_exhausted, rate_limited. See errors and refusals.

Notes

Sessions expire in 30 minutes and the url is single-use. Create a new session rather than reusing one.

Billing follows the headless equivalent: a claim session is billed once per person, a recognise session is free, and a session the person abandons is never billed.

White-label — your logo, accent, copy and your own domain — is included in the free tier. Point a CNAME at Sidaxis and set branding.domain.

The person's reading still happens on their device. Hosted changes who writes the screen, not where the biometric goes.