> ## Documentation Index > Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Change roles for multiple users > Bulk change roles for users in the organization. Supports up to 500 users per request. Cannot modify billing admin roles. Rate limited to 10 requests per 60 seconds with max 3 concurrent requests per organization. > [tab] CLI Tool > > ```bash > coderabbit api request /users/roles --input request.json > ``` > > To install and sign in to the CLI, see [Call from the CLI](https://docs.coderabbit.ai/api/cli.md). > [tab] MCP Server > > This operation isn't a tool on the [CodeRabbit MCP server](https://docs.coderabbit.ai/api/mcp.md). Call it over REST or from the CLI. With `org_id` set to `ALL`, CodeRabbit changes each organization separately, so the change isn't atomic: a user is listed in `succeeded` only when every organization succeeded. See [Change a role on every organization of a self-hosted instance](https://docs.coderabbit.ai/api/guides/users-and-seats.md#change-a-role-on-every-organization-of-a-self-hosted-instance). ## OpenAPI ````yaml /openapi.json post /v1/users/roles openapi: 3.0.0 info: title: CodeRabbit API version: 1.0.0 description: >- Read and manage CodeRabbit reviews, coding tasks, Verify, Triage, security findings, Knowledge Base, configuration, and users for your organization. servers: - url: https://api.coderabbit.ai description: US region - url: https://api.eu.coderabbit.ai description: EU region security: - ApiKeyAuth: [] tags: - name: Organizations and repositories - name: Pull requests and reviews - name: Coding Agent - name: Coding environments - name: Verify - name: Triage - name: Security - name: Knowledge Base - name: Automations - name: Reports - name: Configuration - name: Connections - name: Users and roles - name: Usage and metrics paths: /v1/users/roles: post: tags: - Users and roles summary: Change roles for multiple users description: >- Bulk change roles for users in the organization. Supports up to 500 users per request. Cannot modify billing admin roles. Rate limited to 10 requests per 60 seconds with max 3 concurrent requests per organization. operationId: change-roles requestBody: required: true content: application/json: schema: type: object required: - role - user_ids properties: org_name: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,38}$ description: >- GitHub organization login for a workspace API key, matched case-insensitively. Supply either org_name or org_id, never both; omit for an organization-bound key. org_id: type: string description: >- For workspace-scoped API keys, supply this provider organization ID or org_name, never both. For self-hosted instance keys, use a provider organization ID or ALL (case-insensitive) to apply the role change across active organizations on that instance. Omit it to preserve single-organization behavior for self-hosted keys. Organization keys remain bound to their own organization; ALL is valid only for self-hosted instance keys. role: type: string description: >- Role ID to assign. Use cr_admin, cr_member, or a custom role UUID. cr_billing_admin cannot be assigned through this endpoint. example: 6f1bb6c1-4766-4f09-9d0d-b998c33d2398 user_ids: type: array minItems: 1 maxItems: 500 items: type: string minLength: 1 description: Provider user ID (Git provider's user identifier) description: Array of user IDs to change roles for example: - '121358802' - '234567' responses: '200': description: Role change completed (partial or full success) headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per time window (10) X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current window X-RateLimit-Reset: schema: type: integer description: Unix timestamp when the rate limit resets content: application/json: schema: type: object required: - status - succeeded - failed properties: status: type: string enum: - success - partial_success - failure description: >- Status of the operation - "success" if all succeeded, "partial_success" if some succeeded and some failed, "failure" if all failed example: success succeeded: type: array items: type: string description: Array of user IDs that were successfully processed example: - '121358802' failed: type: array items: type: object required: - user_id - code properties: user_id: type: string description: The user ID that failed code: type: string enum: - USER_NOT_FOUND - CANNOT_CHANGE_BILLING_ADMIN_ROLE description: Error code indicating the reason for failure description: Array of failed users with error codes example: - user_id: '234567' code: CANNOT_CHANGE_BILLING_ADMIN_ROLE '400': description: Invalid request (validation error or business logic error) content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - INVALID_REQUEST - BATCH_SIZE_EXCEEDED - INVALID_ROLE - CANNOT_CHANGE_BILLING_ADMIN_ROLE example: BATCH_SIZE_EXCEEDED message: type: string example: Maximum 500 users per request '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHORIZED example: UNAUTHORIZED message: type: string example: Invalid or inactive API key '403': description: Forbidden - Missing required permission or Enterprise plan content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - FORBIDDEN - ENTERPRISE_PLAN_REQUIRED example: FORBIDDEN message: type: string example: User does not have the required permissions '410': description: >- Legacy API key - deprecated and no longer supported for user management content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - LEGACY_API_KEY example: LEGACY_API_KEY message: type: string example: >- You are using a legacy API key. We are deprecating use of legacy keys. Regenerate a new API key and retry the request. '429': description: Rate limit exceeded or concurrency limit exceeded headers: Retry-After: schema: type: integer description: Seconds to wait before retrying X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per time window X-RateLimit-Remaining: schema: type: integer description: Always 0 when rate limited X-RateLimit-Reset: schema: type: integer description: Unix timestamp when the rate limit resets content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - RATE_LIMIT_EXCEEDED message: type: string '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - INTERNAL_ERROR example: INTERNAL_ERROR message: type: string example: Internal server error security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-coderabbitai-api-key description: >- See [Authentication](/api/authentication) for the key types and where to create a key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.