Auth

14 endpoints

End-user login and signup for directory users in your application. Enable the Auth app in Apps, then enable individual method apps (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 a sub-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. Sub-org-scoped keys automatically target their sub-organization.

Apps and dependencies

Auth must be enabled before any login method works. Method apps (OTP, Email and Password, Magic Link, Social Login, Passkeys, SSO, MFA) require Auth and are toggled independently in Apps. Disabling Auth automatically disables dependent method apps. Method availability in GET /v1/auth/methods reflects both the Auth app and each method app 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 sub-organization. Requires Auth and the corresponding method app 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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Returns a generic response when the user is not found (anti-enumeration). Requires auth.login.

Query Parameters

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

Request Body

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Enforces lockout policy from dashboard settings. Requires auth.login.

Query Parameters

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Respects TTL and rate limits from Magic Link dashboard settings. Requires auth.login.

Query Parameters

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

Request Body

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Request Body

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

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 apps. Requires auth.login.

Query Parameters

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

Request Body

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 assertion from navigator.credentials.get()
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Requires auth.login.

Query Parameters

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Requires auth.login.

Query Parameters

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps; enforces password policy and allow_sign_up from dashboard settings. Requires auth.signup.

Query Parameters

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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 apps. Requires auth.signup.

Query Parameters

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

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

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