Skip to main content
POST
/
api
/
auth
/
workos
/
callback
Handle WorkOS callback (API response mode)
curl --request POST \
  --url https://your-instance.example.com/api/auth/workos/callback \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "01HX9R3K4N6P8QZBVTYM2D5A7C",
  "state": "tether-csrf-7f4b2c1d",
  "redirect_uri": "https://app.tether.example/auth/callback",
  "organizationId": "org_01HX9R3K4N6P8QZBVTYM2D5A7C"
}
'
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI1Zjdi...",
  "refreshToken": "rt_64d2f9c5e8a1d4e001a0b1c2e6f7a8b9",
  "sessionConfig": {
    "enabled": true,
    "idleTimeoutMinutes": 30,
    "tokenExpiryHours": 8,
    "warningTimeMinutes": 2
  },
  "user": {
    "id": "5f7b1c2e8a1d4e0012c3b4a5",
    "email": "admin@acme.example",
    "fullName": "Acme Admin",
    "organizationId": "64a1b2c3d4e5f60012345678",
    "accessRole": "ADMIN"
  }
}

Body

application/json
​
code
string

OAuth authorization code returned by WorkOS/Okta; exchanged server-side (SSO first, AuthKit fallback). Required unless error is set.

​
state
string

Opaque CSRF state token round-tripped from the original /authorize call.

​
error
string

Provider-reported error code; when present the request short-circuits with a 400 instead of attempting code exchange.

​
redirect_uri
string

Redirect URI used in the original /authorize call; must match for the code exchange to succeed. Falls back to ${CLIENT_URL}/signin.

​
organizationId
string

Mongo _id used to assign the org when provisioning a brand-new WorkOS user; falls back to DEFAULT_ORGANIZATION_ID then the oldest org.

Response

Auth session created

Returned by /api/auth/login and POST /api/auth/workos/callback on success. Contains access + refresh tokens, session config, and the resolved user.

​
token
string
required

JWT access token.

​
refreshToken
string
required
​
sessionConfig
object
required

Resolved session configuration returned alongside tokens. Mirrors the org-level idle-timeout / SSO renewal policy so the client can enforce it.

Example:
{
  "enabled": true,
  "idleTimeoutMinutes": 30,
  "tokenExpiryHours": 8,
  "warningTimeMinutes": 2,
  "idleTrackingEnabled": true,
  "ssoSilentRenewalEnabled": true,
  "ssoFallbackBehavior": "redirect",
  "passwordSilentRenewalEnabled": false,
  "passwordFallbackBehavior": "logout"
}
​
user
object
required

Compact User payload returned with auth tokens.

Example:
{
  "id": "5f7b1c2e8a1d4e0012c3b4a5",
  "email": "admin@acme.example",
  "fullName": "Acme Admin",
  "organizationId": "64a1b2c3d4e5f60012345678",
  "accessRole": "ADMIN",
  "conversationOpenPreference": "split"
}