client.auth

Bases: SyncResource

Sync auth namespace (client.auth) — account-level WorkOS/JWT bootstrap.

authorize

authorize(*, redirect_uri: str | None = None, state: str | None = None) -> AuthorizationUrl

Return the hosted WorkOS AuthKit URL to redirect the browser to for sign-in/sign-up. Account-level — no workspace is chosen at login.

Parameters:

Name	Type	Description	Default
redirect_uri	str | None	FE callback URL to return to after login. Must be in the server's allowlist; omit to use the server's first allowed URI.	None
state	str | None	opaque string round-tripped to the callback unchanged (e.g. a return-to path).	None

Raises:

Type	Description
BadRequestError	redirect_uri is not in the allowlist (BAD_REQUEST).

callback

callback(*, code: str) -> AuthTokens

Exchange the one-time AuthKit code (appended to the redirect by WorkOS) for an account-level access+refresh JWT pair. Follow up with client.account.tenants() / client.account.invitations() to route the user — a fresh sign-up simply has empty lists.

Raises:

Type	Description
AuthenticationError	the code is invalid or expired (AUTH_INVALID_CREDENTIAL).

refresh

refresh(*, refresh_token: str) -> AuthTokens

Trade a refresh token for a fresh access+refresh JWT pair.

Parameters:

Name	Type	Description	Default
refresh_token	str	a token from :meth:callback or a prior :meth:refresh.	required

Raises:

Type	Description
AuthenticationError	the refresh token is invalid or expired (AUTH_TOKEN_EXPIRED).
UnprocessableError	refresh_token is empty (VALIDATION_ERROR).

logout

logout() -> None

Revoke the WorkOS session behind the client's access token. Idempotent (a stale/invalid token is a no-op). Returns nothing — the server responds 204. Only meaningful for a JWT-authenticated client; a machine-key client has no WorkOS session to revoke.

Response models

Models returned by client.auth methods (fields, types, and what each means).

Auth + API-key domain models (group g02-auth-keys).

Two credential worlds meet here:

• WorkOS/JWT bootstrap (:class:AuthorizationUrl, :class:AuthTokens) — the browser sign-in flow. A machine sbd_pk_… key holder does NOT use these to "log in"; they already hold a long-lived credential. These surfaces exist for the human/browser AuthKit round-trip and for a JWT-authenticated human to bootstrap their first API key.
• API keys (:class:ApiKey, :class:ApiKeyCreated) — the long-lived machine credentials the SDK/CLI authenticate with. The plaintext is returned exactly once, at creation (:class:ApiKeyCreated); every later read is metadata-only (:class:ApiKey).

Response models use extra="allow" (tolerant reader). No cross-type imports — this is a leaf module in the type dependency graph.

AuthorizationUrl

Bases: BaseModel

Result of :meth:Auth.authorize — the hosted WorkOS AuthKit URL the browser redirects to for sign-in/sign-up. Not used by machine-key holders.

AuthTokens

Bases: BaseModel

The token pair WorkOS issues from :meth:Auth.callback / :meth:Auth.refresh.

access_token is a short-lived (~5 min) JWT sent as Authorization: Bearer <token>; refresh_token trades for a fresh pair via :meth:Auth.refresh. (WorkOS issues no separate id_token.)

ApiKeyCreated

Bases: BaseModel

Response of :meth:ApiKeys.create. Carries plaintext exactly once — the server retains only an argon2id hash, so a lost plaintext is unrecoverable (revoke + re-create). Store it securely; every later read is an :class:ApiKey (no plaintext).

ApiKey

Bases: BaseModel

A metadata-only view of one active API key (list item). Never carries the plaintext — use prefix (e.g. sbd_pk_a3f4…) to tell keys apart.