Cockroach Labs Role Management API

openapi: 3.2.0
info:
  contact:
    email: support@cockroachlabs.com
    name: Cockroach Labs Support
    url: https://support.cockroachlabs.com
  description: An API for managing CockroachDB Cloud resources
  title: CockroachDB Cloud Role Management API
  version: '2026-09-15'
servers:
- url: https://cockroachlabs.cloud
security:
- Bearer: []
tags:
- name: Role Management
paths:
  /api/v1/roles:
    get:
      operationId: CockroachCloud_ListRoleGrants
      summary: List all RoleGrants
      description: 'Can be used by the following roles assigned at the organization scope:

        - ORG_ADMIN

        - CLUSTER_ADMIN

        - FOLDER_ADMIN

        - AUDITOR'
      parameters:
      - name: pagination.page
        in: query
        schema:
          type: string
      - name: pagination.limit
        in: query
        schema:
          type: integer
          format: int32
      - name: pagination.as_of_time
        in: query
        schema:
          type: string
          format: date-time
      - name: pagination.sort_order
        in: query
        description: " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order."
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRoleGrantsResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --url 'https://cockroachlabs.cloud/api/v1/roles?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
  /api/v1/roles/{user_id}:
    get:
      operationId: CockroachCloud_GetAllRolesForUser
      summary: Get all role grants for a user, service account, or group
      description: 'Get all role grants for a user, service account, or group by providing its ID in the user_id path parameter.


        Can be used by the following roles assigned at the organization scope:

        - ORG_ADMIN

        - CLUSTER_ADMIN

        - FOLDER_ADMIN

        - AUDITOR'
      parameters:
      - name: user_id
        in: path
        description: 'user_id is the ID of the user, service account, or group whose roles are

          being retrieved.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllRolesForUserResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --url https://cockroachlabs.cloud/api/v1/roles/{user_id} \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
    put:
      operationId: CockroachCloud_SetRolesForUser
      summary: Replace the roles for a user, service account, or group with exactly those…
      description: 'Replace the entire role set for a user, service account, or group by providing its ID in the user_id path parameter.


        Roles that will be removed or added as a result of this call must follow the CC rules for role assignment:

        https://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles'
      parameters:
      - name: user_id
        in: path
        description: user_id is the ID of the user, service account, or group.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetRolesForUserBody'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllRolesForUserResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request PUT \\\n  --url https://cockroachlabs.cloud/api/v1/roles/{user_id} \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --json '{\"roles\":[{\"name\":\"CLUSTER_ADMIN\",\"resource\":{\"id\":\"example_cluster_id\",\"type\":\"CLUSTER\"}}],\"user_id\":\"12345678-1234-1234-1234-123456789012\"}'"
  /api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name}:
    delete:
      operationId: CockroachCloud_RemoveUserFromRole
      summary: Remove a role from a user, service account, or group
      description: 'Remove a single role from a user, service account, or group by providing its ID in the user_id path parameter. A principal''s last remaining role cannot be removed; because groups do not hold the implicit Org Member role that users and service accounts have, a group must always retain at least one other role.


        Roles that will be removed as a result of this call must follow the CC rules for role assignment:

        https://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles'
      parameters:
      - name: user_id
        in: path
        description: 'user_id is the ID of the user, service account, or group to remove the role

          from.'
        required: true
        schema:
          type: string
      - name: resource_type
        in: path
        description: resource_type is the type of resource the role applies to.
        required: true
        schema:
          type: string
          enum:
          - ORGANIZATION
          - CLUSTER
          - FOLDER
      - name: resource_id
        in: path
        description: 'resource_id is the ID of the resource the role applies to. Pass an empty

          string for organization-scoped roles.'
        required: true
        schema:
          type: string
      - name: role_name
        in: path
        description: role_name is the role to revoke.
        required: true
        schema:
          type: string
          enum:
          - BILLING_COORDINATOR
          - ORG_ADMIN
          - ORG_MEMBER
          - CLUSTER_ADMIN
          - CLUSTER_OPERATOR_WRITER
          - CLUSTER_DEVELOPER
          - CLUSTER_CREATOR
          - FOLDER_ADMIN
          - FOLDER_MOVER
          - METRICS_VIEWER
          - CLUSTER_MONITOR
          - BILLING_VIEWER
          - AUDITOR
          - CLUSTER_DATA_ACCESSOR
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllRolesForUserResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request DELETE \\\n  --url https://cockroachlabs.cloud/api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name} \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
    post:
      operationId: CockroachCloud_AddUserToRole
      summary: Add a role to a user, service account, or group
      description: 'Add a single role to a user, service account, or group by providing its ID in the user_id path parameter.


        Roles that will be added as a result of this call must follow the CC rules for role assignment:

        https://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles'
      parameters:
      - name: user_id
        in: path
        description: user_id is the ID of the user, service account, or group to add the role to.
        required: true
        schema:
          type: string
      - name: resource_type
        in: path
        description: resource_type is the type of resource the role applies to.
        required: true
        schema:
          type: string
          enum:
          - ORGANIZATION
          - CLUSTER
          - FOLDER
      - name: resource_id
        in: path
        description: 'resource_id is the ID of the resource the role applies to. Pass an empty

          string for organization-scoped roles.'
        required: true
        schema:
          type: string
      - name: role_name
        in: path
        description: role_name is the role to grant.
        required: true
        schema:
          type: string
          enum:
          - BILLING_COORDINATOR
          - ORG_ADMIN
          - ORG_MEMBER
          - CLUSTER_ADMIN
          - CLUSTER_OPERATOR_WRITER
          - CLUSTER_DEVELOPER
          - CLUSTER_CREATOR
          - FOLDER_ADMIN
          - FOLDER_MOVER
          - METRICS_VIEWER
          - CLUSTER_MONITOR
          - BILLING_VIEWER
          - AUDITOR
          - CLUSTER_DATA_ACCESSOR
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllRolesForUserResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request POST \\\n  --url https://cockroachlabs.cloud/api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name} \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
  /api/v1/users/persons-by-email:
    get:
      operationId: CockroachCloud_GetPersonUsersByEmail
      summary: Search person users by email address
      description: 'Can be used by the following roles assigned at the organization scope:

        - ORG_ADMIN

        - CLUSTER_ADMIN

        - FOLDER_ADMIN

        - AUDITOR'
      parameters:
      - name: email
        in: query
        description: an email address is required.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPersonUsersByEmailResponse'
        '400':
          description: Returned when a request field is invalid.
          content:
            application/json:
              schema: {}
        '401':
          description: Returned when the token bearer cannot be authenticated.
          content:
            application/json:
              schema: {}
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema: {}
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema: {}
        '500':
          description: Server error
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      tags:
      - Role Management
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --url 'https://cockroachlabs.cloud/api/v1/users/persons-by-email?email=SOME_STRING_VALUE' \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
components:
  schemas:
    SetRolesForUserBody:
      type: object
      properties:
        roles:
          description: roles is the complete set of roles for the user, service account, or group.
          type: array
          items:
            $ref: '#/components/schemas/BuiltInRole'
      example:
        roles:
        - name: CLUSTER_ADMIN
          resource:
            id: example_cluster_id
            type: CLUSTER
        user_id: 12345678-1234-1234-1234-123456789012
      required:
      - roles
    Any:
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nIn its binary encoding, an `Any` is an ordinary message; but in other wire\nforms like JSON, it has a special encoding. The format of the type URL is\ndescribed on the `type_url` field.\n\nProtobuf APIs provide utilities to interact with `Any` values:\n\n- A 'pack' operation accepts a message and constructs a generic `Any` wrapper\n  around it.\n- An 'unpack' operation reads the content of an `Any` message, either into an\n  existing message or a new one. Unpack operations must check the type of the\n  value they unpack against the declared `type_url`.\n- An 'is' operation decides whether an `Any` contains a message of the given\n  type, i.e. whether it can 'unpack' that type.\n\nThe JSON format representation of an `Any` follows one of these cases:\n\n- For types without special-cased JSON encodings, the JSON format\n  representation of the `Any` is the same as that of the message, with an\n  additional `@type` field which contains the type URL.\n- For types with special-cased JSON encodings (typically called 'well-known'\n  types, listed in https://protobuf.dev/programming-guides/json/#any), the\n  JSON format representation has a key `@type` which contains the type URL\n  and a key `value` which contains the JSON-serialized value.\n\nThe text format representation of an `Any` is like a message with one field\nwhose name is the type URL in brackets. For example, an `Any` containing a\n`foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`."
      type: object
      properties:
        '@type':
          description: 'Identifies the type of the serialized Protobuf message with a URI reference

            consisting of a prefix ending in a slash and the fully-qualified type name.


            Example: type.googleapis.com/google.protobuf.StringValue


            This string must contain at least one `/` character, and the content after

            the last `/` must be the fully-qualified name of the type in canonical

            form, without a leading dot. Do not write a scheme on these URI references

            so that clients do not attempt to contact them.


            The prefix is arbitrary and Protobuf implementations are expected to

            simply strip off everything up to and including the last `/` to identify

            the type. `type.googleapis.com/` is a common default prefix that some

            legacy implementations require. This prefix does not indicate the origin of

            the type, and URIs containing it are not expected to respond to any

            requests.


            All type URL strings must be legal URI references with the additional

            restriction (for the text format) that the content of the reference

            must consist only of alphanumeric characters, percent-encoded escapes, and

            characters in the following set (not including the outer backticks):

            `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations

            should not unescape them to prevent confusion with existing parsers. For

            example, `type.googleapis.com%2FFoo` should be rejected.


            In the original design of `Any`, the possibility of launching a type

            resolution service at these type URLs was considered but Protobuf never

            implemented one and considers contacting these URLs to be problematic and

            a potential security issue. Do not attempt to contact type URLs.'
          type: string
      additionalProperties: {}
    GetAllRolesForUserResponse:
      type: object
      properties:
        group_roles:
          type: array
          items:
            $ref: '#/components/schemas/BuiltInFromGroups'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/BuiltInRole'
    UserRoleGrants:
      type: object
      properties:
        roles:
          description: roles is the complete set of roles for the user, service account, or group.
          type: array
          items:
            $ref: '#/components/schemas/BuiltInRole'
        user_id:
          description: user_id is the ID of the user, service account, or group.
          type: string
      example:
        roles:
        - name: CLUSTER_ADMIN
          resource:
            id: example_cluster_id
            type: CLUSTER
        user_id: 12345678-1234-1234-1234-123456789012
      required:
      - user_id
      - roles
    ListRoleGrantsResponse:
      type: object
      properties:
        grants:
          type: array
          items:
            $ref: '#/components/schemas/UserRoleGrants'
        pagination:
          $ref: '#/components/schemas/KeysetPaginationResponse'
        user_group_grants:
          type: array
          items:
            $ref: '#/components/schemas/UserGroupRoleGrant'
    UserGroupRoleGrant:
      type: object
      properties:
        group_roles:
          type: array
          items:
            $ref: '#/components/schemas/BuiltInFromGroups'
        user_id:
          type: string
    Resource:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/ResourceType.Type'
      required:
      - type
    Status:
      type: object
      properties:
        code:
          type: integer
          format: int32
        details:
          type: array
          items:
            $ref: '#/components/schemas/Any'
        message:
          type: string
    GetPersonUsersByEmailResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/PersonUserInfo'
      required:
      - users
    PersonUserInfo:
      type: object
      properties:
        email:
          description: email is an email address.
          type: string
        id:
          description: id is the user id.
          type: string
      required:
      - id
      title: person_user_info contains information about a person
    OrganizationUserRole.Type:
      description: " - FOLDER_ADMIN: Preview: A folder admin role.\n - FOLDER_MOVER: Preview: A folder mover role.\n - AUDITOR: Limited Access: An auditor role with org-wide, read-only visibility into configuration, identity, authorization, audit logs, and cluster metadata.\n - CLUSTER_DATA_ACCESSOR: Limited Access: A cluster data accessor role with SQL and data access to clusters (databases, SQL shell, DB Console) without cluster-management privileges."
      type: string
      enum:
      - BILLING_COORDINATOR
      - ORG_ADMIN
      - ORG_MEMBER
      - CLUSTER_ADMIN
      - CLUSTER_OPERATOR_WRITER
      - CLUSTER_DEVELOPER
      - CLUSTER_CREATOR
      - FOLDER_ADMIN
      - FOLDER_MOVER
      - METRICS_VIEWER
      - CLUSTER_MONITOR
      - BILLING_VIEWER
      - AUDITOR
      - CLUSTER_DATA_ACCESSOR
    KeysetPaginationResponse:
      type: object
      properties:
        next_page:
          type: string
        previous_page:
          type: string
    BuiltInFromGroups:
      type: object
      properties:
        group_names:
          type: array
          items:
            type: string
        role:
          $ref: '#/components/schemas/BuiltInRole'
    BuiltInRole:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/OrganizationUserRole.Type'
        resource:
          $ref: '#/components/schemas/Resource'
      required:
      - name
      - resource
    ResourceType.Type:
      description: " - ORGANIZATION: An organization.\n - CLUSTER: A cluster resource.\n - FOLDER: Preview: A folder resource."
      type: string
      enum:
      - ORGANIZATION
      - CLUSTER
      - FOLDER
    SetRolesForUserRequest:
      type: object
      description: Request body for setting all roles for a user.
      required:
      - roles
      properties:
        roles:
          type: array
          description: Complete set of role grants to assign to the user.
          items:
            type: object
    Error:
      type: object
      description: Standard error response returned by the API.
      properties:
        code:
          type: integer
          description: HTTP status code of the error.
        message:
          type: string
          description: Human-readable description of the error.
        details:
          type: array
          description: Additional detail objects providing error context.
          items:
            type: object
    PaginationResponse:
      type: object
      description: Pagination metadata included in list responses.
      properties:
        next:
          type: string
          description: Token or cursor for retrieving the next page of results.
        last:
          type: string
          description: Token or cursor for the last page of results.
        time:
          type: string
          format: date-time
          description: Server time at which the paginated query was executed.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Generate a token in the CockroachDB Cloud Console under Organization Settings > API Access.
  parameters:
    paginationPage:
      name: pagination.page
      in: query
      description: Page number for paginated results, starting from 1.
      schema:
        type: string
    resourceId:
      name: id
      in: path
      required: true
      description: Unique identifier of the resource.
      schema:
        type: string
    paginationAsOfTime:
      name: pagination.as_of_time
      in: query
      description: RFC3339 timestamp to return results as they were at a specific point in time (time-travel query).
      schema:
        type: string
        format: date-time
    userId:
      name: user_id
      in: path
      required: true
      description: Unique identifier of the user.
      schema:
        type: string
    paginationLimit:
      name: pagination.limit
      in: query
      description: Maximum number of results to return per page.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 500
    paginationSortOrder:
      name: pagination.sort_order
      in: query
      description: Sort direction for paginated results. Accepted values are ASC and DESC.
      schema:
        type: string
        enum:
        - ASC
        - DESC
    roleName:
      name: role_name
      in: path
      required: true
      description: Name of the role to grant or revoke.
      schema:
        type: string
    resourceType:
      name: resource_type
      in: path
      required: true
      description: Type of resource the role is scoped to. Accepted values include ORGANIZATION, FOLDER, CLUSTER.
      schema:
        type: string
        enum:
        - ORGANIZATION
        - FOLDER
        - CLUSTER
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: Use the CockroachDB Cloud API
  url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api.html