Complete WorkOS login

OpenAPI contract

Method

POST

Path

/api/v1/auth/workos/callback

Security

None

Response status

200 400 429 500

Request and response schemas

JSON

{
  "requestBody": {
    "application/json": {
      "$ref": "#/components/schemas/WorkOsCallbackRequest"
    }
  },
  "responses": {
    "200": {
      "description": "Session created",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/AuthResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

POST /api/v1/auth/workos/callback is public. Send the nonblank authorization code and state returned by WorkOS, together with the browserProof stored by the initiating tab when login started. Never redeem a callback that has no matching local attempt. The proof is single-use and expires after ten minutes; start login again after expiry or a failed exchange.

A successful callback returns the same session-token fields as password login: access token, refresh token, token type, and access-token lifetime.

The browser proof, authorization code, and returned tokens are secrets. Send them only to this HTTPS endpoint and keep them out of logs and telemetry. Never add the browser proof to the provider or callback URL. Invalid, expired, or failed WorkOS exchanges are authentication errors.

http

POST /api/v1/auth/workos/callback
Content-Type: application/json