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
| Role | Name | What the role can do |
|---|---|---|
OWNER | Owner | Everything an Admin can do, plus the owner-only actions: making another user an Owner (Assign Owner API) and deleting the workspace. |
ADMIN | Admin | 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. |
MANAGER | Manager | Sees and manages every conversation and client, broadcasts and reports. Cannot change the workspace configuration. |
AGENT_PLUS | Agent+ | Manages clients and sees their unmasked details. Only sees conversations assigned to them plus unassigned ones. |
AGENT | Agent | Only sees conversations assigned to them plus unassigned ones. Client email, phone and |
Permissions
Endpoints check a permission, not a role name. Each permission is granted to these roles:
| Permission | Granted to | Needed for |
|---|---|---|
MANAGE_OWNER | Owner | Owner-only actions such as assignOwner |
MANAGE_WORKSPACE | Owner, Admin | Workspace configuration, usersRoles, assignUserRole, unassignUserRole |
MANAGE_CONVS | Owner, Admin, Manager | Acting on any conversation, broadcasts, reports |
MANAGE_CLIENTS | Owner, 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.
mereports it asADMIN. - An agent API key acts as its linked agent and is capped at the Agent+ role.
mereports it asAGENT_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
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The role record ID. |
userId | string | The Bread Crumbs user ID that holds the role. |
email | string | The user's email, saved when the role record was created. Later role changes do not update it. |
role | Role | The role: |
createdAt | DateTime | 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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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:
| Caller | role | id and userId | email | createdAt |
|---|---|---|---|---|
| User session | The user’s stored role | The role record ID and the user ID | The email saved on the role | When the role was created |
| Workspace API key | ADMIN | The API key record ID | Empty string | Time of the request |
| Agent API key | AGENT_PLUS | The linked agent ID | The agent’s email | Time of the request |
A workspace API key is not limited by role checks; ADMIN is only how me reports it.
| Error | Cause |
|---|---|
User not Authenticated | The 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. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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.
| Error | Cause |
|---|---|
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
userId | string | Required. The Bread Crumbs user ID of the member. |
email | string | 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. |
role | Role | Required. The new role: |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
This request is not allowed to be called using API Key | Called with a workspace API key. |
You do not have permission to access this resource with your current role assignment | The calling user is not an Owner or Admin, or the call uses an agent API key. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
userId | string | Required. The Bread Crumbs user ID of the member. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
This request is not allowed to be called using API Key | Called with a workspace API key. |
You do not have permission to access this resource with your current role assignment | The calling user is not an Owner or Admin, or the call uses an agent API key. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
userId | string | Required. The Bread Crumbs user ID of the new Owner. |
email | string | Required. The new Owner's email. Saved only when a new role record is created. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
This request is not allowed to be called using API Key | Called with a workspace API key. |
You do not have permission to access this resource with your current role assignment | The calling user is not an Owner, or the call uses an agent API key. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
Programming language examples
cURL
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}"}'