---
title: "Roles"
method: POST
path: "/v1/users/roles"
---

# Roles

`POST /v1/users/roles`

Bulk change roles for up to 500 users. Returns partial success with details of which users succeeded or failed.

## Headers

- `x-coderabbitai-api-key` string, required

## Request body

- ChangeRolesRequest — Request to change user roles
  - `role` 'cr_admin' | 'cr_member', required — CodeRabbit user role to assign
  - `user_ids` string[], required — Array of provider user IDs
  - `org_id` string — Optional organization scope for self-hosted instance API keys. Set to `ALL` (case-insensitive) to apply the role change across every active organization on the self-hosted instance in one request. Set to a provider organization ID to target one organization on the self-hosted instance. Omit `org_id` to preserve the prior single-organization behavior. The `ALL` sentinel is valid only with self-hosted instance API keys; organization, workspace, and legacy keys cannot use it.

## Response `200`

Operation completed (check status field for partial failures)

- BulkOperationResponse — Response for bulk operations with partial success model
  - `status` 'success' | 'partial_success' | 'failure', required — Operation status: 'success' if all succeeded, 'partial_success' if some succeeded, 'failure' if all failed
  - `succeeded` string[], required — Array of user IDs that were successfully processed
  - `failed` BulkOperationFailure[], required — Array of failures with error details
    - `user_id` string, required — Identifier that failed: a provider user ID, or the supplied `cr_user_id`/`email` when the request used a workspace API key
    - `code` string, required — Error code

## Other responses

- `400` — Invalid request
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Not an admin or missing Enterprise plan
- `410` — Legacy API key - deprecated and no longer supported for user management
- `429` — Rate limit exceeded (10 requests per 60 seconds per organization)
- `500` — Internal server error

---

[API](https://skmtc.net/coderabbit/apis/coderabbit-api-spec.md) · [All operations](https://skmtc.net/coderabbit/apis/coderabbit-api-spec/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coderabbit/coderabbit-api-spec/versions/401789d85d01/schema)