CumulusDocs
Open Studio
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 use path).
  • MCP tool: sdk_client_call with operationId: "team.set_role" (path arguments use input.path). Legacy alias: team_set_role. Connect to your authenticated /mcp endpoint 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
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

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

FieldType or valuesRequiredDescription and limits
role"owner" · "admin" · "member" · "viewer"Optional—
can_dialbooleanOptional—
Complete OpenAPI schema
OpenAPI JSON
{
  "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

FieldType or valuesRequiredDescription and limits
user_idstring (uuid)Requiredpattern: ^([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})$.
emailstringRequiredpattern: ^(?:[A-Za-z0-9_'+-]+.)[A-Za-z0-9_'+-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*.)+[A-Za-z]{2,}$.
namestring or nullRequiredmaxLength: 256.
role"owner" · "admin" · "member" · "viewer"Required—
can_dialbooleanRequired—
joined_atstring (date-time)Requiredpattern: ^(?:(?:\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

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "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
OpenAPI JSON
{
  "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.

Content version a3e66fcdCustomer SDKMarkdown source
Change a member’s role · Cumulus developer docs