Manage Users

Manage who can access a Builder Content Space. Use these operations to list users, add existing organization members to a Space, change their roles, and remove them from a Space or from the entire organization.

Authentication and permissions

Listing users with users works with either a private key (bpk) or a personal access token (btk-). Every other operation on this page reads or changes individual membership, so it requires a personal access token. Private keys are rejected.

Send the token in the Authorization header as Bearer btk-....
Pass the ID of the Space you are working on as the apiKey query parameter, for example https://cdn.builder.io/api/v2/admin?apiKey=YOUR_SPACE_API_KEY.
For mutations, the token owner must be an admin of that Space.
The roles you can assign are admin, editor, and developer.
You cannot change your own role or remove yourself with this API.
Changes take effect immediately. Users do not need to log out.

Get users

Retrieve all users from a Builder Content Space.

Framework

const response = await adminSDK .query({ users: { id: true, name: true, email: true, role: true, lastActive: true } });

Get a user

Retrieve a single user of the Space by ID. The response is null if the user is not a member of the Space. Requires a personal access token.

Framework

Query

query { user(id: "USER_ID") { id name email role lastActive } }

Response

{ "data": { "user": { "id": "USER_ID", "name": "Elena Aguilar", "email": "elena@builder.io", "role": "editor", "lastActive": 1746049078845 } } }

Add a user to a Space

Add an existing member of the parent organization to a Space with the given role. This is not an invitation flow: the user must already belong to the organization. The apiKey must be a Space, not the root organization or an environment.

Framework

Mutation

mutation { addUserToSpace(userId: "USER_ID", role: "editor") { id name email role } }

Response

{ "data": { "addUserToSpace": { "id": "USER_ID", "name": "Elena Aguilar", "email": "elena@builder.io", "role": "editor" } } }

Update a user role

Change the role of a user who is already a member of the Space. The apiKey must be a Space, not the root organization or an environment.

Framework

Mutation

mutation { updateUserRole(userId: "USER_ID", role: "developer") { id name email role } }

Response

{ "data": { "updateUserRole": { "id": "USER_ID", "name": "Elena Aguilar", "email": "elena@builder.io", "role": "developer" } } }

Remove a user from a Space

Remove a user from a Space and its environments. If this leaves the user in no organization, their sessions and personal access tokens are also revoked. The apiKey must be a Space, not the root organization or an environment. To offboard a user from everything, use Remove a user from an organization.

Framework

Mutation

mutation { removeUserFromSpace(userId: "USER_ID") }

Response

{ "data": { "removeUserFromSpace": true } }

Remove a user from an organization

Remove a user from an organization and all of its Spaces. If this leaves the user in no organization, their sessions and personal access tokens are also revoked. Unlike the Space operations, the apiKey query parameter must be the ID of the root organization, not a Space.

Framework

Mutation

mutation { removeUserFromOrganization(userId: "USER_ID") }

Response

{ "data": { "removeUserFromOrganization": true } }

What's next

Continue to explore the Admin API documentation or use the GraphQL Explorer to try out these queries with your own Space and Organization. Then, visit the Admin API GraphQL Schema for more details on how to modify your queries.

Was this article helpful?