> ## 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 up to 500 users. Returns partial success with details of which users succeeded or failed.

export const EnterprisePlanBadge = ({tip = "This feature is available exclusively as part of the Enterprise plan. Please refer to our pricing page for more information about our plans and features.", title = "Enterprise Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="building-2" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<EnterprisePlanBadge />

## Change User Roles

<Info>
  Requires **Admin** role. See [Role-based access](/management/roles) for details.
</Info>


## OpenAPI

````yaml 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 up to 500 users. Returns partial success with
        details of which users succeeded or failed.
      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: []
        '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
          enum:
            - cr_admin
            - cr_member
          description: CodeRabbit user role to assign
        user_ids:
          type: array
          items:
            type: string
          description: Array of provider user IDs
          minItems: 1
          maxItems: 500
      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:
        id:
          type: string
          description: User ID that failed
        code:
          type: string
          description: Error code
      required:
        - 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.

````