Sessions

Sessions are short-lived, single-use tokens that authorize a client (web widget, mobile SDK, or hosted link) to run a single domain connect flow.

Create Session

Mint a short-lived session token for client-side use. This endpoint must be called server-to-server using your secret API key.

POST/v1/sessions

Headers

Authorization: Bearer sk_live_{your_secret_key}
Content-Type: application/json
Idempotency-Key: (optional) unique string

Request body

Field	Type	Required	Description
`user_id`	string	yes	Your app's user identifier.
`domain`	string	no	Domain to connect, if known ahead of time.
`allowed_providers`	string[]	no	Restrict the flow to specific providers.
`expires_in`	integer	no	TTL in seconds (default: 3600, max: 86400).
`nonce`	string	yes	Unique string for replay protection.

Example request

curl -X POST https://api.dns.global/v1/sessions \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
  "user_id": "user_456",
  "domain": "shop.example.com",
  "expires_in": 3600,
  "nonce": "a1b2c3d4"
}'

Response — 201 Created

{
  "session_token": "sess_abc123def456...",
  "expires_at": "2026-06-01T13:00:00Z"
}

Errors

Code	Meaning
401	Invalid or missing secret key
422	Validation error (missing required fields)
429	Rate limit exceeded

Keep your secret key server-side

Session creation must happen on your backend. If a secret key is exposed in client code, rotate it immediately from your dashboard.

Next steps

Detect a provider for the session's domain
Initiate a domain connection