Start WorkOS login

OpenAPI contract

Method

POST

Path

/api/v1/auth/workos/login/{provider}

Security

None

Response status

200 400 429 500

Request and response schemas

JSON

{
  "requestBody": {},
  "responses": {
    "200": {
      "description": "Authorization URL",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/WorkOsLoginResponse"
        }
      }
    },
    "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/login/{provider} is public. Replace {provider} with a supported WorkOS provider. The response contains url, state, browserProof, and expiresAt for a ten-minute, single-use login attempt.

Before opening url, store browserProof in the initiating tab's session storage, keyed by state. Keep the proof out of URLs, logs, and telemetry. Complete the callback only when its state matches a stored, unexpired attempt. The server handles PKCE and rejects missing, mismatched, expired, or reused proofs.

This endpoint does not create a Nativify session. Do not treat the returned URL as a credential or modify its authorization parameters. Unsupported providers, disabled WorkOS authentication, or incomplete configuration are reported as errors.

http

POST /api/v1/auth/workos/login/{provider}