Exchange the headless SSO one-time token for a session token

Server-to-server: requires an enterprise service API key (Bearer or x-api-key). Exchanges the one-time token issued by /api/customer-auth/enterprise-return (single-use, 60 s TTL) for the buyer’s session token. Plain body, no { data } envelope.

POST/api/customer-auth/enterprise-exchange

Authorization

AuthorizationAPI key · headerrequired

API key prefixed with Bearer . Alternative: the x-api-key header with the raw key. Available scopes: read and write (see /.well-known/oauth-protected-resource).

x-api-keyAPI key · headerrequired

Raw API key (without Bearer ), alternative to Authorization.

Header parameters

X-Workspace-Idstring

Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).

Request body

requiredapplication/json

tokenstringrequired

One-time token received on the landing page callback (format {slug}.{token}, forwarded as is).

min length 1 · max length 256

Responses

200

Buyer session exchanged.

session_tokenstringrequired

Buyer session token. Send it as the X-Customer-Session header on /api/v1/customer/*.

expires_atstringrequired

Session expiry (ISO 8601, 7-day sliding window).

customerobjectrequired

Show properties

idstringrequired

emailstringrequired

namestringrequired

email_verifiedbooleanrequired

401

Missing or invalid API key, or invalid/expired token.

403

The API key doesn't belong to an enterprise service user, or the token was minted for another workspace.

422

Invalid body.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

X-Workspace-IdheaderActive workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).

Bodyapplication/json

tokenstring*One-time token received on the landing page callback (format `{slug}.{token}`, forwarded as is).

Request

curl -X POST '/api/customer-auth/enterprise-exchange' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "string"
}'

const response = await fetch("/api/customer-auth/enterprise-exchange", {
  method: "POST",
  headers: {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"token\": \"string\"\n}"
});

import requests

response = requests.post(
    "/api/customer-auth/enterprise-exchange",
    headers={
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    data="{\n  \"token\": \"string\"\n}",
)

Response

{
  "session_token": "string",
  "expires_at": "string",
  "customer": {
    "id": "string",
    "email": "string",
    "name": "string",
    "email_verified": true
  }
}