Manage organization members

Members of an organization can see its Boxes and create Boxes in it. Their role decides what they can manage, and a grant on a Box lets them run commands in it, SSH into it, reach it over the private network and open its console. This guide shows how owners and admins manage both. Organizations and access explains roles, grants and guest accounts.

Before you beginCopy Anchor Link

• These requests need a sign-in session. They refuse API keys with 403 api_key_not_allowed, and the SDK has no methods for them.
• For the CLI, run cubicle login, and unset CB_CLI_API_KEY, which replaces the stored login.
• The curl examples read a session token from CUBICLE_SESSION_TOKEN. Sign people in from your tool shows how to get one. Some examples use jq to read JSON.
• The Dashboard manages grants on a Box's Access tab, but it cannot add, remove or change members. Use the CLI or the API for those.

The examples use the organization acme, where you are an owner, and a colleague dev@example.com.

Who can do whatCopy Anchor Link

Any member can list the organization's members and a Box's grants, and revoke their own grant. Owners and admins add and remove members, change roles, and grant and revoke access to Boxes; an admin can remove owners too. Roles has the full table.

• Only an owner can make someone an owner. An admin who tries gets 403 forbidden "only owners can add owners".
• The other owner and admin actions fail for a member with 403 forbidden "organization admin role required".
• A member cannot leave an organization by themselves. An owner or admin removes them.
• The last owner cannot be removed.

List membersCopy Anchor Link

Any active member can list the organization's members.

cubicle members list --org acme
# 1f4a9b7c-2d3e-4f50-8a6b-7c8d9e0f1a2b  acme/ci  member  active
# 6b9e0d2c-41af-4c3b-8e2d-5f7a9c1b3d4e  dev@example.com  member  active
# 9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a  ops@example.com  owner  active

• Members are sorted by identity. A person's identity is their email address; a service account's is ORG/NAME.
• Removed members stay in the list with status revoked.
• The user ID is what the remove and grant commands take.

Add a personCopy Anchor Link

cubicle members add --org acme dev@example.com --role member
# dev@example.com is member

• The person must already have a Cubicle account. Cubicle is invite-only: a Cubicle operator creates accounts and sends invitations, so ask a Cubicle operator to invite a colleague who has none. You can add them as soon as their account exists, before they first sign in.
• Give their identity exactly as their account has it. cubicle whoami prints it. An unknown identity fails with 404 not_found "user not found".
• A new member has no grants. To let them use a Box, grant them access.
• The new member sees the organization in cubicle whoami.

Change a member's roleCopy Anchor Link

Add the member again with the new role. The request sets the role you send, whether it is higher or lower than their current one.

cubicle members add --org acme dev@example.com --role admin
# dev@example.com is admin

• Without --role, the CLI sends member, so adding an existing admin or owner without it makes them a member.
• An admin can lower an owner's role, but only an owner can give the owner role.
• Adding a removed member makes them active again with the role you send.

Remove a memberCopy Anchor Link

cubicle members rm --org acme 6b9e0d2c-41af-4c3b-8e2d-5f7a9c1b3d4e

What removal does:

• Their membership becomes revoked. The organization and its Boxes disappear for them: requests for them return 404.
• Their access to every Box in the organization ends. Their guest accounts are locked and lose their SSH keys, and their private network and console access ends. Files in their home directories stay on the Boxes' disks.
• Their grants stay on record, and cubicle grants list still shows them as active. They give no access while the person is not a member, and they apply again if you add the person back. To end them for good, revoke them too.
• Boxes they created stay in the organization in their current state, with their vCPUs, memory and disk still reserved. Owners and admins can still start, stop and delete them. To run commands in one, grant yourself access to it.
• Their Cubicle account, their personal organization and their other memberships do not change.

A user who is not an active member fails with 404 not_found "membership not found". Removing the last owner fails with 409 last_owner "an organization needs at least one owner".

Grant access to a BoxCopy Anchor Link

The user who creates a Box gets a grant on it automatically. Owners and admins grant access to any other active member of the Box's organization, people and service accounts alike, including themselves. The owner and admin roles give no shell-level access by themselves, so they need a grant too.

Find the user ID first. For a person, it is the first column of cubicle members list, as in List members. For a service account, it is the first column of cubicle service-accounts list:

cubicle service-accounts list --org acme
# 8b0e2c1d-4f6a-4b8e-9c3d-2a7f5e1b0c94  acme/ci  member
#   key 5c9d7e3a-1b2f-4c8d-a6e5-0f9b8c7d6e5a  github-actions  write  cbk_7Hq2xP9a…  last used 2026-11-05T10:00:00.000Z

Then add the grant with that ID:

cubicle grants add acme/job-1 6b9e0d2c-41af-4c3b-8e2d-5f7a9c1b3d4e

In the Dashboard, an owner or admin opens the Box, chooses the member under Grant Box access to member on its Access tab, and chooses Add grant.

• The grant creates the member's guest account in the Box. The Box's Node applies it, also while the Box runs. Until it has, an exec fails with an error ending in unknown guest account; retry it after a few seconds.
• Granting a revoked grant again makes it active.
• A user who is not an active member of the Box's organization fails with 404 not_found "member not found".

Check the grant and the guest account it created. Each line is <user ID> <identity> <status> <guest account>:

cubicle grants list acme/job-1
# 6b9e0d2c-41af-4c3b-8e2d-5f7a9c1b3d4e  dev@example.com  active  jv_6b9e0d2c41af
# 8b0e2c1d-4f6a-4b8e-9c3d-2a7f5e1b0c94  acme/ci  active  jv_8b0e2c1d4f6a

Check that the grant has reached the Box:

cubicle grants list acme/job-1 --json |
  jq '.[] | select(.identity == "dev@example.com") | .desiredRevision == .appliedRevision'
# => true

Revoke access to a BoxCopy Anchor Link

Owners and admins can revoke any grant. A member can revoke only their own.

cubicle grants rm acme/job-1 6b9e0d2c-41af-4c3b-8e2d-5f7a9c1b3d4e

In the Dashboard, choose Revoke next to the grant on the Box's Access tab.

• Revoking locks the guest account and removes its SSH keys, and ends the member's private network access to the Box. Its files stay on the disk. See Revoking access.
• You can revoke the grant of someone you have removed from the organization.
• A user without an active grant on the Box fails with 404 not_found "grant not found".

Service accounts as membersCopy Anchor Link

A service account is a member of the one organization that owns it, with the role member or admin. Create it with cubicle service-accounts create, not members add (see Run CI jobs in Boxes), grant it Boxes like a person, and see Service accounts for what it can do.

• To change its role, add it again: cubicle members add --org acme acme/ci --role admin. Making it an owner, or adding another organization's service account, fails with 400 invalid_request "constraint violated".
• Removing it ends it, as cubicle service-accounts rm does: its API keys stop working, its name is free for a new service account, and it stays in the list as revoked under a changed identity such as acme/ci#1f4a9b7c. It cannot be used again; create a new service account instead. Its Boxes stay, as a removed person's do.

TroubleshootingCopy Anchor Link

• api_key_not_allowed: API keys cannot use this route: see API keys.
• 403 forbidden "only owners can add owners" or "organization admin role required": your role does not allow the action; see Who can do what and ask an owner or admin.
• not_found: organization not found: the organization name is wrong, or you are not an active member of it.
• not_found: user not found on add: no account has that exact identity. Check it with the person, or ask a Cubicle operator to invite them.
• not_found: member not found on a grant: the user ID belongs to no active member of the Box's organization. Add them first.

RelatedCopy Anchor Link

• Organizations and access: roles, grants, guest accounts and service accounts.
• Account and access commands: cubicle members, grants and service-accounts.
• SSH into a Box: what a member does with a grant, SSH and editors.
• Add a member (API): POST /v1/orgs/{org}/members.