Skip to Content
API ReferenceMembers & Roles

Members & Roles APIs

Open in the app: Workspace settings

Overview

Every user who works in a workspace has a role in that workspace. The role decides which APIs the user can call and what they see in the portal. Roles are per workspace, so the same user can be an Owner in one workspace and an Agent in another. For the portal view of the same model, see Workspace Roles.

Roles

RoleNameWhat the role can do
OWNEROwner

Everything an Admin can do, plus the owner-only actions: making another user an Owner (Assign Owner API) and deleting the workspace.

ADMINAdmin

Manages the workspace configuration (channels, agents, API keys, webhooks, tags, quick replies, workspace settings, uploads and member roles), all conversations and all clients. Cannot perform owner-only actions.

MANAGERManager

Sees and manages every conversation and client, broadcasts and reports. Cannot change the workspace configuration.

AGENT_PLUSAgent+

Manages clients and sees their unmasked details. Only sees conversations assigned to them plus unassigned ones.

AGENTAgent

Only sees conversations assigned to them plus unassigned ones. Client email, phone and externalClientId are masked.

Permissions

Endpoints check a permission, not a role name. Each permission is granted to these roles:

PermissionGranted toNeeded for
MANAGE_OWNEROwnerOwner-only actions such as assignOwner
MANAGE_WORKSPACEOwner, AdminWorkspace configuration, usersRoles, assignUserRole, unassignUserRole
MANAGE_CONVSOwner, Admin, ManagerActing on any conversation, broadcasts, reports
MANAGE_CLIENTSOwner, Admin, Manager, Agent+Creating and changing clients, unmasked client details, contact imports

Endpoints that only need a role on the workspace accept every role, Agent included. A user who has no role in the workspace gets Missing role assignment for the target user, and a role without the permission gets You do not have permission to access this resource with your current role assignment.

API keys and roles

  • A workspace API key is not limited by role checks and has full workspace access. me reports it as ADMIN.
  • An agent API key acts as its linked agent and is capped at the Agent+ role. me reports it as AGENT_PLUS.

See What changes when a key is linked to an agent for details.

Role changes need a user session. assignUserRole, unassignUserRole and assignOwner reject workspace API keys and agent API keys. Call them with the session token of an Owner or Admin (Authorization: Bearer <token>); assignOwner needs an Owner. The request examples on this page use the API-KEY placeholder, so replace it with the session token for these three mutations. me and usersRoles work with workspace API keys.

Members and roles

Members are invited to and removed from a workspace in the portal. These APIs only manage the role record of a user ID in the workspace: they do not invite users or change the member list. A member who has no role record yet gets one the first time they open the workspace in the portal: the first user of a new workspace becomes its Owner, everyone else starts as Agent.

userId is the Bread Crumbs user ID. Read it from the List User Roles API or from the userId of the user’s agent.

User role properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The role record ID.

userIdstring

The Bread Crumbs user ID that holds the role.

emailstring

The user's email, saved when the role record was created. Later role changes do not update it.

roleRole

The role: OWNER, ADMIN, MANAGER, AGENT_PLUS or AGENT.

createdAtDateTime

When the role record was created.

Get My Role API

Get the caller’s role in a workspace. Use it to check what the current token or API key is allowed to do.

For a user session it returns the user’s stored role record. It also makes sure the user has an agent profile in the workspace: it creates one with the user’s name and email when it is missing, and updates the agent’s email and user ID when they changed. API keys get a generated record instead, see the table below.

Access: Any authenticated caller, no permission required. Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query me($input: InputInitWorkspace!) { me(input: $input) { id userId email role createdAt } } input InputInitWorkspace { workspaceId: Int! # Workspace ID. }

The query above returns JSON structured like this:

{ "data": { "me": { "id": "apikey_123", "userId": "apikey_123", "email": "", "role": "ADMIN", "createdAt": "2026-10-17T09:30:00.000Z" } } }

The example response is for a workspace API key. What me returns for each kind of caller:

Callerroleid and userIdemailcreatedAt
User sessionThe user’s stored roleThe role record ID and the user IDThe email saved on the roleWhen the role was created
Workspace API keyADMINThe API key record IDEmpty stringTime of the request
Agent API keyAGENT_PLUSThe linked agent IDThe agent’s emailTime of the request

A workspace API key is not limited by role checks; ADMIN is only how me reports it.

ErrorCause
User not AuthenticatedThe Authorization header is missing, or the token or API key is not valid.
Cannot return null for non-nullable field Query.me.The calling user has no role in this workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"me","variables":{"input":{"workspaceId":12}},"query":"query me($input: InputInitWorkspace!) {\n me(input: $input) {\n id\n userId\n email\n role\n createdAt\n }\n}"}'

List User Roles API

List the role records of a workspace, newest first. The list is not paginated.

Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query usersRoles($input: InputUsersRoles!) { usersRoles(input: $input) { nodes { id userId email role createdAt } } } input InputUsersRoles { workspaceId: Int! # Workspace ID. }

The query above returns JSON structured like this:

{ "data": { "usersRoles": { "nodes": [ { "id": "role_789", "userId": "user_789", "email": "[email protected]", "role": "AGENT", "createdAt": "2026-10-15T08:12:00.000Z" }, { "id": "role_456", "userId": "user_456", "email": "[email protected]", "role": "ADMIN", "createdAt": "2026-09-02T11:40:00.000Z" }, { "id": "role_123", "userId": "user_123", "email": "[email protected]", "role": "OWNER", "createdAt": "2026-06-01T07:05:00.000Z" } ] } } }

Only users with a role record are listed. A member who has not opened the workspace in the portal yet may have no record; the portal shows such members as Agent.

ErrorCause
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
Missing role assignment for the target userThe calling user has no role in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"usersRoles","variables":{"input":{"workspaceId":12}},"query":"query usersRoles($input: InputUsersRoles!) {\n usersRoles(input: $input) {\n nodes {\n id\n userId\n email\n role\n createdAt\n }\n }\n}"}'

Assign User Role API

Set a user’s role in a workspace. If the user already has a role there, it is replaced; otherwise a new role record is created. The new role applies from the user’s next request.

Access: MANAGE_WORKSPACE (Owner, Admin), user session only. Workspace API keys and agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

userIdstring

Required. The Bread Crumbs user ID of the member.

emailstring

Required. The member's email. Saved only when a new role record is created; when an existing role is replaced, the stored email is kept.

roleRole

Required. The new role: ADMIN, MANAGER, AGENT_PLUS or AGENT. To make a user an Owner, use the Assign Owner API.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation assignUserRole($input: InputAssignUserRole!) { assignUserRole(input: $input) { id userId email role createdAt } } input InputAssignUserRole { workspaceId: Int! # Workspace ID. userId: String! # Bread Crumbs user ID of the member. email: String! # Member email, saved on new role records. role: Role! # New role. } enum Role { OWNER ADMIN MANAGER AGENT AGENT_PLUS }

The mutation above returns JSON structured like this:

{ "data": { "assignUserRole": { "id": "role_456", "userId": "user_456", "email": "[email protected]", "role": "MANAGER", "createdAt": "2026-09-02T11:40:00.000Z" } } }

This call only changes the role record. It does not invite the user, add them to the workspace member list or create their agent profile; invite members from the portal. The agent profile is created the first time the member opens the workspace.

ErrorCause
This request is not allowed to be called using API KeyCalled with a workspace API key.
You do not have permission to access this resource with your current role assignmentThe calling user is not an Owner or Admin, or the call uses an agent API key.
Missing role assignment for the target userThe calling user has no role in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"assignUserRole","variables":{"input":{"workspaceId":12,"userId":"user_456","email":"[email protected]","role":"MANAGER"}},"query":"mutation assignUserRole($input: InputAssignUserRole!) {\n assignUserRole(input: $input) {\n id\n userId\n email\n role\n createdAt\n }\n}"}'

Unassign User Role API

Remove a user’s role from a workspace. Returns true, also when the user had no role.

Access: MANAGE_WORKSPACE (Owner, Admin), user session only. Workspace API keys and agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

userIdstring

Required. The Bread Crumbs user ID of the member.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation unassignUserRole($input: InputUnassignUserRole!) { unassignUserRole(input: $input) } input InputUnassignUserRole { workspaceId: Int! # Workspace ID. userId: String! # Bread Crumbs user ID of the member. }

The mutation above returns JSON structured like this:

{ "data": { "unassignUserRole": true } }

Only the role record is deleted. The user stays in the workspace member list, and their agent profile and conversation assignments are kept. If the user is still a member and opens the workspace in the portal again, they get the Agent role back automatically. To take someone out of the workspace, use Remove on the users list in the portal, which also removes the membership.

ErrorCause
This request is not allowed to be called using API KeyCalled with a workspace API key.
You do not have permission to access this resource with your current role assignmentThe calling user is not an Owner or Admin, or the call uses an agent API key.
Missing role assignment for the target userThe calling user has no role in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"unassignUserRole","variables":{"input":{"workspaceId":12,"userId":"user_789"}},"query":"mutation unassignUserRole($input: InputUnassignUserRole!) {\n unassignUserRole(input: $input)\n}"}'

Assign Owner API

Make a user an Owner of the workspace. If the user has a role, it is changed to OWNER; if not, an Owner role record is created with the given email.

Access: MANAGE_OWNER (Owner only), user session only. Workspace API keys and agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

userIdstring

Required. The Bread Crumbs user ID of the new Owner.

emailstring

Required. The new Owner's email. Saved only when a new role record is created.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation assignOwner($input: InputAssignUserOwner!) { assignOwner(input: $input) { id userId email role createdAt } } input InputAssignUserOwner { workspaceId: Int! # Workspace ID. userId: String! # Bread Crumbs user ID of the new Owner. email: String! # Email, saved on new role records. }

The mutation above returns JSON structured like this:

{ "data": { "assignOwner": { "id": "role_456", "userId": "user_456", "email": "[email protected]", "role": "OWNER", "createdAt": "2026-09-02T11:40:00.000Z" } } }

Ownership transfer. The caller keeps the Owner role, so after this call the workspace has two Owners and both can perform owner-only actions. To finish a transfer, the previous Owner then changes their own role with the Assign User Role API, for example to ADMIN.

ErrorCause
This request is not allowed to be called using API KeyCalled with a workspace API key.
You do not have permission to access this resource with your current role assignmentThe calling user is not an Owner, or the call uses an agent API key.
Missing role assignment for the target userThe calling user has no role in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"assignOwner","variables":{"input":{"workspaceId":12,"userId":"user_456","email":"[email protected]"}},"query":"mutation assignOwner($input: InputAssignUserOwner!) {\n assignOwner(input: $input) {\n id\n userId\n email\n role\n createdAt\n }\n}"}'