Users

List the people with access to the workspace and change their roles programmatically. Roles map to the same three levels shown under Configuration > Users: admin (full access), builder (manages agents and the resources they depend on), or member (standard access).

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

Every user endpoint is admin only. A non-admin caller gets 403.

These endpoints read and write roles for users who already exist. Inviting someone, enabling or disabling an account, and auto-add by email domain stay in the application — see User management.

The user object

User. Unlike most of the API, these fields are camelCase rather than snake_case, matching OIDC role mapping.

Field	Type	Description
id	string	User ID (UUID) — the `user_id` used to change a role.
email	string	Email address, or null.
firstName	string	Given name.
lastName	string	Family name.
role	string	`admin`, `builder`, or `member`.
disabled	boolean	Whether the account is disabled. A disabled user keeps their role but can't sign in.
lastActiveAt	string	When the user was last active, or null if they never signed in.
createdAt	string	When the account was created.

List users

GET /users

Lists the workspace's users and their roles, most recently created last. Disabled users are included, flagged by disabled.

Parameter	In	Type	Required	Description
limit	query	integer	No	Page size, 1–1000. Defaults to 100.
offset	query	integer	No	Number of users to skip. Defaults to 0.

curl 'https://{your-deployment-host}/api/v2/users?limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response — a PaginatedResponse of User

{
  "next": null,
  "has_more": true,
  "data": [
    {
      "id": "04ec0e3d-968c-4cf8-9f60-19508acf726f",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "role": "admin",
      "disabled": false,
      "lastActiveAt": "2026-08-13T10:11:35.643Z",
      "createdAt": "2026-02-09T11:13:38.420Z"
    }
  ]
}

Page with offset, not next. next is reserved for a future cursor and is always null today, so a client that follows it stops after the first page — use has_more to decide whether to request the next offset.

An out-of-range limit or a negative offset returns 400.

Change a user's role

PATCH /users/{user_id}

Assigns a role to an existing user. The change is propagated to the identity provider, the workspace database, and the agent server, and it ends the target user's sessions — they're signed out and must sign in again to pick up the new role.

Parameter	In	Type	Required	Description
user_id	path	string	Yes	User ID (UUID).

Body

Field	Type	Required	Description
role	string	Yes	`admin`, `builder`, or `member`.

curl -X PATCH 'https://{your-deployment-host}/api/v2/users/04ec0e3d-968c-4cf8-9f60-19508acf726f' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "role": "builder" }'

Returns the updated User.

On OIDC workspaces with a group→role mapping, don't manage roles here. The identity provider is the source of truth: a role set through this endpoint is overwritten at the user's next login or token refresh. Manage those users through the provider's groups and the OIDC role mapping endpoints instead.

The last admin can't be demoted

A workspace must keep at least one admin, so demoting the only remaining one fails with 409 and nothing is written. Only enabled admins count toward that total — disabling every other admin leaves the last enabled one undemotable.

Promoting someone else to admin first makes the demotion succeed.

Errors

Status	When
400	The user ID isn't a valid UUID, or the role isn't one of the three.
403	The caller isn't an admin.
404	No user exists with that ID.
409	The target user is the last remaining admin.

API keys OIDC role mapping