Sign in

v15

latestOpenAPI 3.0.0MIT Licenseraw.githubusercontent.com2026-08-016088119.5 KB
authentication

Sign in with an OAuth2 provider

Initiate OAuth2 authentication flow with a social provider. Redirects the user to the provider's authorization page. If the user doesn't exist and AUTH_DISABLE_AUTO_SIGNUP is not set, a new account will be created upon callback. When AUTH_DISABLE_AUTO_SIGNUP is enabled, users must use the /signup/provider/{provider} endpoint to register first.

get/signin/provider/{provider}

Path parameters

provider'apple' | 'github' | 'google' | 'linkedin' | 'discord' | 'spotify' | 'twitch' | 'gitlab' | 'bitbucket' | 'workos' | 'azuread' | 'entraid' | 'strava' | 'facebook' | 'windowslive' | 'twitter' required

The name of the social provider

Query parameters

allowedRolesstring[]

Array of allowed roles for the user

[
  "me",
  "user"
]
defaultRolestring
Example:user

Default role for the user

displayNamestring
Example:John Smith

Display name for the user

localestring
Example:en

A two or three characters locale

Additional metadata for the user (JSON encoded string)

redirectTostring uri
Example:https://my-app.com/catch-redirection

URI to redirect to

connectstring

If set, this means that the user is already authenticated and wants to link their account. This needs to be a valid JWT access token.

statestring

Opaque state value to be returned by the provider

connectionstring

(workos) Specifies the connection to use for authentication

organizationstring

(workos) Specifies the organization to use for authentication

Additional provider-specific parameters

upstreamParamsobject

Extra parameters forwarded to the upstream OAuth2 provider's authorization URL (e.g. Google's prompt or login_hint). Reserved OAuth2/OIDC parameters are rejected.

Extra parameters forwarded to the upstream OAuth2 provider's authorization URL. Reserved OAuth2/OIDC parameters are rejected.

codeChallengestring

PKCE code challenge (S256). When provided, the callback redirect will contain an authorization code instead of a refresh token.

Response

An error occurred while processing the request

statusinteger required

HTTP status error code

messagestring required

Human-friendly error message

error'default-role-must-be-in-allowed-roles' | 'disabled-endpoint' | 'disabled-user' | 'user-already-exists' | 'email-already-verified' | 'forbidden-anonymous' | 'internal-server-error' | 'invalid-email-password' | 'invalid-request' | 'locale-not-allowed' | 'password-too-short' | 'password-in-hibp-database' | 'redirectTo-not-allowed' | 'role-not-allowed' | 'signup-disabled' | 'unverified-user' | 'user-not-anonymous' | 'invalid-pat' | 'invalid-refresh-token' | 'invalid-ticket' | 'disabled-mfa-totp' | 'no-totp-secret' | 'invalid-totp' | 'mfa-type-not-found' | 'totp-already-active' | 'invalid-state' | 'oauth-token-echange-failed' | 'oauth-profile-fetch-failed' | 'oauth-provider-error' | 'invalid-otp' | 'otp-too-many-attempts' | 'cannot-send-sms' | 'provider-account-already-linked' required

Error code identifying the specific application error

Example response

{
  "status": 400,
  "message": "Invalid email format"
}