Class AuthClient

List supported auth methods Returns the complete catalogue of authentication methods the platform supports, including each method's stable slug, user-facing name, and description. Use this endpoint to render method labels in sign-in UIs or org settings screens without hardcoding copy or maintaining your own enum list. Results reflect the platform's source-of-truth catalogue and are consistent across all orgs. This endpoint requires only a publishable key and is accessible without an active user session, making it suitable for pre-authentication flows such as login page rendering or onboarding configuration.

Exchange a one-time login token for session tokens Exchanges an email-login token (including email reply links) or an internal impersonation login token for session credentials. Passwordless magic-link tokens from /api/v1/auth/login/link, /api/v1/auth/register/link, or /api/v1/auth/request/link must instead go to /api/v1/auth/verify/link. Numeric email codes go to /api/v1/auth/code/verify with email and code. Access and refresh tokens are not accepted here. Invalid, expired, or already-used login tokens return HTTP 401 with structured error.type, error.code, and error.message fields. If timezone is provided and the user's current timezone is still the default ("America/Los_Angeles"), the account timezone is updated in the same request. Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.

Authenticate with email and password Authenticates a user with an email address and password and returns a short-lived access token, a refresh token, and the authenticated user object. Use the refresh token with the /auth/refresh endpoint to obtain new access tokens without re-authenticating. Password login must be enabled for the app; apps that have disabled password authentication return HTTP 403. Requests are rate-limited per IP (10 per minute) and per email-IP pair (5 per minute) — exceeding either limit returns HTTP 429.

Refresh an access token Exchanges a valid refresh token for a new access token and a new refresh token, rotating the refresh token on every call. The response also includes the updated user object. Store the new refresh token and discard the old one. Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401. Rate limiting is applied per (user, IP) pair when the token can be verified, and falls back to IP-only when it cannot. The limit is 30 exchanges per minute per bucket; exceeding it returns HTTP 429.

Register a new user with email and password Creates a new user account and returns an access token, refresh token, and the new user object. Two registration paths are supported:

• Team registration: supply team_invite with a valid team invite ID. The new user is added to that team immediately upon registration. Returns HTTP 404 if the invite is not found.
• Standard registration: supply password. An invite_code may optionally be included for invite-gated apps; an invalid code returns HTTP 404. Provide team_invite or password; when both are supplied, team registration takes precedence. Omitting both returns HTTP 400. Unknown fields return HTTP 400 with field-level guidance. Use full_name for the profile name (returned as user.name); name is not an input field. alias is a separate optional handle. Legacy team_invite_id remains accepted; team_invite takes precedence. Password registration must be enabled for the app; disabled apps return HTTP 403. The response status is HTTP 201 on success.

Request a magic link for login Sends a magic link to the given email address so an existing user can sign in without a password. The user clicks the link in their email and is redirected to redirect_uri with a token; pass that token to /api/v1/auth/verify/link to obtain session tokens. If no account exists for the email, the endpoint still returns success to prevent email enumeration — no link is sent in that case. Both email and redirect_uri are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

Request a magic link for login or registration Sends a passwordless magic link to the given email address. If an account with that email already exists, a login link is sent. If no account exists, a registration link is sent and the recipient completes sign-up by clicking through. This unified endpoint lets you implement a single email-entry UI that handles both cases transparently. The redirect_uri is validated against the app's registered hosts; an unregistered URI returns HTTP 400. Both email and redirect_uri are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns HTTP 204 on success — no body. If the app has Allowed Users enabled and the address is not on the list, returns HTTP 403 user_not_allowed. That refusal is the same for new and existing addresses, so it does not reveal whether an account exists. For a new user, full_name and (with set_org) the org details ride the pending registration and are applied when the link is verified; nothing is created before the click. They are ignored when the email already belongs to a user. Malformed values return HTTP 422 before the address is looked up, so the response cannot reveal whether an account exists.

Request a magic link for registration Starts a passwordless registration flow by sending a verification link to the given email address. The recipient clicks the link and is redirected to redirect_uri with a token; pass that token to /api/v1/auth/verify/link to complete registration and obtain session tokens. Profile fields (full_name, alias, timezone) and, with set_org, the org details are captured now and applied when the link is verified; nothing is created before the click. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

Verify a magic link token Consumes a single-use token from a magic link URL and returns an access token, refresh token, and the authenticated user object. This endpoint completes both the login flow (initiated by /api/v1/auth/login/link) and the registration flow (initiated by /api/v1/auth/register/link or /api/v1/auth/request/link). Extract the token from the token query parameter of the magic link redirect URI and POST JSON {"token":"<token from redirect URI>"} to /api/v1/auth/verify/link, not /api/v1/auth/token. Expired or already-used tokens return HTTP 401 — expired links have error.code = authentication_error and error.message = expired_token; unknown or already-used tokens have error.message = invalid_or_expired_token. If the app has disabled passwordless authentication the request returns HTTP 403. Rate-limited to 10 requests per IP per minute — exceeding this returns HTTP 429.