Skip to main content
POST
Login with password or impersonation token

Body

application/json

Provide either password or impersonationToken with email.

email
string<email>
required

Login email; used to look up the user before credential check.

password
string

Plain-text password; verified via WorkOS when the user is migrated, otherwise via the local bcrypt hash. Mutually exclusive with impersonationToken.

impersonationToken
string

Single-use JWT issued by /api/auth/impersonate/{userId}; must carry the isImpersonation flag and match email. Mutually exclusive with password.

Response

Login successful

Returned by /api/auth/login and POST /api/auth/workos/callback on success. Contains access + refresh tokens, session config, and the resolved user.

token
string
required

JWT access token.

refreshToken
string
required
sessionConfig
object
required

Resolved session configuration returned alongside tokens. Mirrors the org-level idle-timeout / SSO renewal policy so the client can enforce it.

Example:
user
object
required

Compact User payload returned with auth tokens.

Example: