client.users

Bases: SyncResource

Sync users namespace (client.users).

create

create(*, email: str, first_name: str, last_name: str, password: str, role: WorkspaceRole | str = WorkspaceRole.MEMBER) -> User

Create a ready-to-login member directly — programmatic SEEDING only (admin; 201). No email is sent; the account is created with the given password. Humans join via client.invitations.create + their in-app accept (ADR-0113).

Parameters:

Name	Type	Description	Default
email	str	login email for the seeded account; must be unique within the workspace (409 USER_EMAIL_TAKEN otherwise).	required
first_name	str	given name on the new user's profile.	required
last_name	str	family name on the new user's profile.	required
password	str	initial password the account logs in with; must satisfy the identity provider's strength rules.	required
role	WorkspaceRole | str	workspace role to grant — admin or member (default member); controls the seeded account's permissions.	MEMBER

Raises:

Type	Description
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).
ConflictError	email already a member (USER_EMAIL_TAKEN) or user quota reached (RESOURCE_LIMIT_EXCEEDED).
UnprocessableError	invalid email/name/password (incl. WorkOS password-strength rejection).

leave

leave() -> None

Leave this workspace (204). The account survives; the membership and its API keys go. The last admin can't leave (400 LAST_ADMIN).

remove

remove(user_id: UUID | str) -> None

Remove a member from this workspace (admin; 204). Removing yourself is :meth:leave; the last admin is guarded (400 LAST_ADMIN).

Raises:

Type	Description
NotFoundError	unknown user id (USER_NOT_FOUND).
BadRequestError	target is yourself, or the last admin (LAST_ADMIN).

me

me() -> User

Fetch the authenticated user's own row.

update_me

update_me(*, first_name: str | None = None, last_name: str | None = None) -> User

Edit your own first/last name (only the fields you pass change).

Email and password have dedicated flows (email is IdP-managed; use :meth:change_my_password for the password).

change_my_password

change_my_password(*, previous_password: str, new_password: str) -> None

Change your own password (204, returns nothing).

previous_password is re-verified against the identity provider before new_password is set.

Raises:

Type	Description
AuthenticationError	the current password is wrong (AUTH_INVALID_CREDENTIAL).
BadRequestError	the account has no password credential to rotate (BAD_REQUEST).
UnprocessableError	the request body is malformed (empty fields / new password below the minimum length).

list

list(*, q: str | None = None, role: WorkspaceRole | str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[User]

List workspace users, newest first (cursor-paginated; iterate for all).

Open to any tenant user (not admin-only).

Parameters:

Name	Type	Description	Default
q	str | None	case-insensitive substring matched against email + first/last name.	None
role	WorkspaceRole | str | None	filter to admin or member.	None

Raises:

Type	Description
BadRequestError	malformed pagination cursor (INVALID_CURSOR).
UnprocessableError	invalid role enum value.

update_role

update_role(user_id: UUID | str, *, role: WorkspaceRole | str) -> User

Change a workspace user's role (admin-only).

Parameters:

Name	Type	Description	Default
role	WorkspaceRole | str	the new workspace role — admin or member.	required

Raises:

Type	Description
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).
NotFoundError	no such user in this tenant (USER_NOT_FOUND).
BadRequestError	would demote the only remaining admin (BAD_REQUEST) — promote a replacement first.

Response models

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

User domain models.

OWNERSHIP (STYLE.md): this module owns User (the full workspace-user row) and UserSummary (the compact reference other domains embed). It sits LOW in the type-module dependency order (common ← jobs ← users ← …) so later domains — project members, asset state, comments — import UserSummary from here rather than re-declaring it.

UserSummary

Bases: BaseModel

Compact user reference embedded in other responses (project members, asset state, comment authors) to spare callers an N+1 name lookup.

User

Bases: BaseModel

A workspace user: identity + workspace role (admin/member).