> ## 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. # Roles > 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. Requires user_management:write and an Enterprise plan. ## OpenAPI ````yaml /openapi.json post /v1/users/roles openapi: 3.0.3 info: title: CodeRabbit API spec version: 1.0.0 servers: - url: https://api.coderabbit.ai security: - ApiKeyAuth: [] paths: /v1/users/roles: post: summary: Roles 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. Requires user_management:write and an Enterprise plan. operationId: change-roles parameters: - name: x-coderabbitai-api-key description: Your CodeRabbit API key required: true example: cr-xxxxxxxxxx schema: type: string in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChangeRolesRequest' examples: promote: summary: Promote users to admin value: role: cr_admin user_ids: - '121358802' - '22605247' demote: summary: Change users to member value: role: cr_member user_ids: - '121358802' - '22605247' responses: '200': description: Operation completed (check status field for partial failures) content: application/json: schema: $ref: '#/components/schemas/BulkOperationResponse' example: status: success succeeded: - '121358802' - '22605247' failed: [] 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: description: Unix timestamp when the rate limit resets schema: type: integer '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: BATCH_SIZE_EXCEEDED message: Maximum 500 users per request '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: UNAUTHORIZED message: Invalid or inactive API key '403': description: Forbidden - Not an admin or missing Enterprise plan content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: NOT_ADMIN message: Only administrators can perform seat management operations '410': description: >- Legacy API key - deprecated and no longer supported for user management content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: LEGACY_API_KEY message: >- 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 (10 requests per 60 seconds per organization) content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Max 10 requests per 60 seconds headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per time window schema: type: integer X-RateLimit-Remaining: description: Always 0 when rate limited schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the rate limit resets schema: type: integer '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: INTERNAL_ERROR message: Internal server error while listing users security: - ApiKeyAuth: [] components: schemas: ChangeRolesRequest: type: object description: Request to change user roles properties: 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. minLength: 1 user_ids: type: array items: type: string minLength: 1 description: Array of provider user IDs minItems: 1 maxItems: 500 org_id: type: string description: >- Required for workspace-scoped API keys: the provider organization ID within the workspace. 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. minLength: 1 required: - role - user_ids additionalProperties: false BulkOperationResponse: type: object description: Response for bulk operations with partial success model properties: status: type: string enum: - success - partial_success - failure description: >- Operation status: 'success' if all succeeded, 'partial_success' if some succeeded, 'failure' if all failed succeeded: type: array items: type: string description: Array of user IDs that were successfully processed failed: type: array items: $ref: '#/components/schemas/BulkOperationFailure' description: Array of failures with error details required: - status - succeeded - failed additionalProperties: false ApiError: type: object description: Standard API error response properties: error: type: object properties: code: type: string description: Error code identifier message: type: string description: Human-readable error message required: - code - message additionalProperties: false required: - error additionalProperties: false BulkOperationFailure: type: object description: Failed operation details properties: user_id: type: string description: >- Identifier that failed: a provider user ID, or the supplied `cr_user_id`/`email` when the request used a workspace API key code: type: string description: Error code required: - user_id - code additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-coderabbitai-api-key description: >- API key for authentication. You can create an API key from the CodeRabbit dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.