On this page
Change a member’s role
Change a workspace member’s role.
Operation ID: team.set_role.
Request
PATCH /api/v1/team/members/{user_id}
- TypeScript SDK:
client.team.set_role(path arguments usepath). - MCP tool:
sdk_client_callwithoperationId: "team.set_role"(path arguments useinput.path). Legacy alias:team_set_role. Connect to your authenticated/mcpendpoint with an API key for the same environment. - Minimum API key role: admin.
- Idempotency: No header required; the resource or revision identifies the change.
Read resource IDs from earlier responses and use a key for the same environment.
Request example
Use the user ID returned by team.list for the intended teammate. This grants member access while leaving outbound dial permission disabled. Check the updated membership; do not assume a role change also changes other users or API keys.
Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.
cURL
curl --fail-with-body -sS -X PATCH "${CUMULUS_BASE_URL%/}/api/v1/team/members/${USER_ID}" \
-H "Authorization: Bearer $CUMULUS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"role": "member",
"can_dial": false
}'
TypeScript
import { Cumulus } from "@cumulus/sdk";
const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });
const response = await client.team.set_role({
"path": {
"user_id": "<user_id>"
},
"body": {
"role": "member",
"can_dial": false
}
});
Input schema
Path, query and header parameters
user_id
path parameter · Required.
Type: string (uuid). pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
JSON request body
| Field | Type or values | Required | Description and limits |
|---|---|---|---|
role | "owner" · "admin" · "member" · "viewer" | Optional | — |
can_dial | boolean | Optional | — |
Complete OpenAPI schema
{
"parameters": [
{
"name": "user_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamSetRoleRequest"
}
}
}
}
}
Responses
HTTP 200
Change a member's role
application/json
| Field | Type or values | Required | Description and limits |
|---|---|---|---|
user_id | string (uuid) | Required | pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$. |
email | string | Required | pattern: ^(?:[A-Za-z0-9_'+-]+.)[A-Za-z0-9_'+-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*.)+[A-Za-z]{2,}$. |
name | string or null | Required | maxLength: 256. |
role | "owner" · "admin" · "member" · "viewer" | Required | — |
can_dial | boolean | Required | — |
joined_at | string (date-time) | Required | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$. |
Error responses
| HTTP | Description |
|---|---|
| 4XX | Typed error (ApiError) |
| 5XX | Typed error (ApiError) |
Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.
Complete OpenAPI schema
{
"200": {
"description": "Change a member's role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamSetRoleResponse200"
}
}
}
},
"4XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"5XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
Referenced schemas
Expand the complete OpenAPI definitions for integrations that generate their own clients.
Complete OpenAPI schema
{
"components": {
"schemas": {
"TeamSetRoleRequest": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"viewer"
]
},
"can_dial": {
"type": "boolean"
}
},
"additionalProperties": false
},
"TeamSetRoleResponse200": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
},
"email": {
"type": "string",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"name": {
"nullable": true,
"type": "string",
"maxLength": 256
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"viewer"
]
},
"can_dial": {
"type": "boolean"
},
"joined_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"user_id",
"email",
"name",
"role",
"can_dial",
"joined_at"
],
"additionalProperties": false
},
"ApiError": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden",
"not_found",
"conflict",
"invalid_request",
"idempotency_conflict",
"policy_denied",
"capability_unavailable",
"provider_unavailable",
"knowledge_unavailable",
"publication_invalid",
"run_not_active",
"rate_limited",
"outcome_unknown",
"internal"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"outcome": {
"type": "string",
"enum": [
"none",
"unknown"
]
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"code",
"message",
"retryable",
"outcome"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
Errors and recovery
See API error handling and Troubleshooting.