Auth

21 endpoints

End-user login and signup for directory users in your application. Enable the Auth service in Services, then enable individual method services (OTP, Email and Password, Magic Link, Social Login, Passkeys, SSO). Your backend calls these routes with an API key — end-users never see the key. Use GET /v1/auth/methods to discover which methods are available for an organization.

auth.login

auth.signup

auth.settings.read

auth.settings.write

Authenticate with your organization API key. Include subOrgId as a query parameter or in the request body when using an org-wide key. Organization-scoped keys automatically target their organization.

Services and dependencies

Auth must be enabled before any login method works. Method services (OTP, Email and Password, Magic Link, Social Login, Passkeys, SSO, MFA) require Auth and are toggled independently in Services. Disabling Auth automatically disables dependent method services. Method availability in GET /v1/auth/methods reflects both the Auth service and each method service being enabled, plus provider/connection configuration for social and SSO.

Dashboard configuration

Session lifetime, concurrent session limits, and default open signup are configured on the Auth dashboard page (/dashboard/os/auth). Email/password policy and lockout rules are on the Email and Password page. Magic link TTL and rate limits are on the Magic Link page. OTP format and delivery are on the OTP page. Social providers and SSO connections have their own dashboard pages.

Session response

Successful login and signup routes return a session object. expires_in reflects the access token lifetime configured in Auth settings (seconds). An OS session row is recorded for session management APIs.

{ "session": { "access_token": "eyJ...", "refresh_token": "v1...", "expires_in": 3600, "user_id": "uuid-of-auth-user", "directory_user_id": "uuid-of-directory-user" } }

Browser OAuth and SSO callbacks

Social login and SSO complete in the browser. Start flows with the API routes below, then WordAuth redirects to your redirectUri with tokens after the IdP callback. These callback URLs do not accept API keys.

# Social OAuth callback (browser redirect, no API key) GET /api/v1/auth/login/social/callback?state=...&code=... # OIDC SSO callback GET /api/v1/auth/login/sso/oidc/callback?state=...&code=... # SAML ACS (form POST from IdP) POST /api/v1/auth/login/sso/saml/acs

After a successful social or OIDC login, the user is redirected to your redirectUri with access_token, refresh_token, expires_in, user_id, and directory_user_id query parameters.

Methods

GET

/v1/auth/methods

Returns login methods available for the organization. Requires Auth and the corresponding method service to be enabled. Social methods include enabled providers; SSO methods include active connections. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "methods": [ { "id": "otp", "label": "OTP" }, { "id": "password", "label": "Email and password", "providers": null }, { "id": "social", "label": "Social login", "providers": ["google"] } ] }

Login

POST

/v1/auth/login/otp/send

Send a login OTP to an active directory user. Requires Auth and OTP services. Returns a generic response when the user is not found (anti-enumeration). Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "otp_id": "...", "expires_at": "...", "delivery_hint": "j•••@example.com", "delivery_method": "email" }

POST

/v1/auth/login/otp/verify

Verify the login OTP and return session tokens. Registers an OS session and syncs org membership. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
otp_id	string	Yes	The otp_id returned from /v1/otp/generate
code	string	Yes	The word pair entered by the user
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "user_id": "...", "directory_user_id": "..." } }

POST

/v1/auth/login/password

Sign in with email and password for a provisioned directory user. Requires Auth and Email and Password services. Enforces lockout policy from dashboard settings. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password (min 8 characters for signup)
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/password/reset/send

Send a self-serve password reset email. Never reveals whether the user exists. Requires auth.login and password reset enabled.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
redirectTo	string	No	Optional URL embedded in the email action link
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "delivery_hint": "j•••@example.com" }

POST

/v1/auth/password/reset/confirm

Confirm a password reset with the recovery token hash and a new password. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
token_hash	string	Yes	Magic link or recovery token hash from the email link
password	string	Yes	User password (min 8 characters for signup)
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/invite/accept

Accept a directory user invite by setting a password. Returns a session. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
token	string	Yes	Directory user invite token from the invitation email
password	string	Yes	User password (min 8 characters for signup)
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/login/magic-link/send

Email a sign-in link to an active directory user. Requires Auth and Magic Link services. Respects TTL and rate limits from Magic Link dashboard settings. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
redirectTo	string	No	Optional URL embedded in the email action link
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "delivery_hint": "j•••@example.com" }

POST

/v1/auth/login/magic-link/verify

Exchange the token_hash from the magic link for session tokens. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
token_hash	string	Yes	Magic link or recovery token hash from the email link
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/login/passkey/options

Start a WebAuthn passkey login ceremony for a user with registered credentials. Requires Auth and Passkeys services. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "options": { /* WebAuthn request options */ }, "challengeId": "..." }

POST

/v1/auth/login/passkey/verify

Verify the passkey assertion from navigator.credentials.get() and return session tokens. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
challengeId	string	Yes	Passkey challenge ID from the options response
credential	object	Yes	WebAuthn credential from navigator.credentials.create() or get()
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/login/social/start

Returns an OAuth authorization_url for an enabled provider (google, github, apple, microsoft). Redirect the user's browser there; after callback, tokens are sent to your redirectUri. Requires Auth and Social Login services. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
provider	string	Yes	google, github, apple, or microsoft
redirectUri	string	Yes	Your app URL to receive OAuth/SSO tokens after login
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "authorization_url": "https://...", "state": "..." }

POST

/v1/auth/login/sso/start

Returns an IdP authorization_url for an active SAML or OIDC connection. Requires Auth and SSO services. Requires auth.login.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
connectionId	string	Yes	SSO connection ID from the dashboard or GET /v1/sso/connections
redirectUri	string	Yes	Your app URL to receive OAuth/SSO tokens after login
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "authorization_url": "https://...", "state": "..." }

Signup

POST

/v1/auth/signup

Create an auth account for a provisioned directory user, or register when openSignup is true (defaults from Auth dashboard settings when omitted). Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
firstName	string	No	First name
lastName	string	No	Last name
phone	string	No	Phone number
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "user_id": "...", "directory_user_id": "..." } }

POST

/v1/auth/signup/password

Register with email and password. Requires Auth and Email and Password services; enforces password policy and allow_sign_up from dashboard settings. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password (min 8 characters for signup)
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }

POST

/v1/auth/signup/otp/send

Start OTP-verified signup — provisions the directory user when openSignup is true, then sends a code. Requires Auth and OTP services. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "otp_id": "...", "expires_at": "...", "delivery_hint": "...", "delivery_method": "email" }

POST

/v1/auth/signup/otp/verify

Complete OTP-verified signup and return session tokens. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
otp_id	string	Yes	The otp_id returned from /v1/otp/generate
code	string	Yes	The word pair entered by the user
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "user_id": "...", "directory_user_id": "..." } }

POST

/v1/auth/signup/authenticate-email/send

Send an authenticate-your-email link for open signup. Does not provision the directory user until the link is verified. Requires open signup (org Auth setting or openSignup: true). Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
redirectTo	string	No	Optional URL embedded in the email action link
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
firstName	string	No	First name
lastName	string	No	Last name
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "delivery_hint": "u•••@example.com" }

POST

/v1/auth/signup/authenticate-email/verify

Verify the authenticate-email token, provision the directory user if needed, and return session tokens. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
token_hash	string	Yes	Magic link or recovery token hash from the email link
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "user_id": "...", "directory_user_id": "..." } }

POST

/v1/auth/signup/passkey/options

Start a WebAuthn passkey signup ceremony for a directory user (create if open signup). Requires Auth and Passkeys services and passkey allow_sign_up. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
firstName	string	No	First name
lastName	string	No	Last name
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "options": { /* WebAuthn create options */ }, "challengeId": "..." }

POST

/v1/auth/signup/passkey/verify

Verify the passkey attestation, store the credential on the directory user, and return session tokens. Requires auth.signup.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
email	string	Yes	User email address
challengeId	string	Yes	Passkey challenge ID from the options response
credential	object	Yes	WebAuthn credential from navigator.credentials.create() or get()
deviceName	string	No	Optional friendly name for the passkey
openSignup	boolean	No	When true, create a new directory user if one does not exist. When omitted, defaults to the Auth dashboard open signup setting.
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "user_id": "...", "directory_user_id": "..." } }