PingCAP Member API

openapi: 3.2.0
info:
  description: '*TiDB Cloud API is in beta.*


    # Overview


    The TiDB Cloud API is a REST interface that provides you with programmatic access to manage administrative objects within TiDB Cloud.'
  title: IAM System OPEN Member API
  contact: {}
  version: v1beta1
servers:
- url: https://iam.tidbapi.com/v1beta1
tags:
- name: Member
paths:
  /members:
    get:
      description: Lists all members in your organization. You can filter the results by email address, role, status, project ID, or instance ID.
      tags:
      - Member
      summary: List members
      parameters:
      - description: The maximum number of members to return. If not specified, at most 100 members will be returned.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: 'The pagination token received from a previous `List members` request. Use this token to retrieve the next page of results.


          **Note**: When paginating, all other parameters must match the original request.'
        name: pageToken
        in: query
        schema:
          type: string
      - description: Filters the results by email address. Only members whose email matches the specified value are returned.
        name: email
        in: query
        schema:
          type: string
      - description: 'Filters the results by one or more roles. Only members assigned any of the specified roles are returned.


          To specify multiple roles, repeat the `roles` parameter for each value. For example, `?roles=org:owner&roles=org:member`.'
        name: roles
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - org:owner
            - org:member
            - org:billing_admin
            - org:billing_viewer
            - org:audit_admin
            - project:owner
            - project:dev
            - project:readonly
            - project:ctl_plane_viewer
            - cluster:admin
            - cluster:viewer
            type: string
      - description: 'Filters the results by one or more member statuses. Only members in any of the specified statuses are returned.


          To specify multiple statuses, repeat the `statuses` parameter for each value. For example, `?statuses=Active&statuses=Pending`.'
        name: statuses
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - Active
            - Pending
            type: string
      - description: 'Specifies the sorting order of results. Use a supported field name, optionally followed by `asc` (ascending order) or `desc` (descending order). For example, `email desc`. By default, results are sorted in ascending order.


          Supported fields: `email`, `invite_time`, `login_time`.'
        name: orderBy
        in: query
        schema:
          type: string
          enum:
          - email asc
          - email desc
          - invite_time asc
          - invite_time desc
          - login_time asc
          - login_time desc
      - description: The ID of the project. If specified, only members assigned to the specified project are returned.
        name: projectId
        in: query
        schema:
          type: string
      - description: The ID of the TiDB Cloud Starter, Essential, or Premium instance. If specified, only members assigned to the specified instance are returned.
        name: instanceId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiListUsersRsp'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://iam.tidbapi.com/v1beta1/members'"
      operationId: getMembers
      x-operation-id-source: derived
    post:
      description: Invites one or more users to your organization. You can also assign organization, project, and instance roles to the invited members in the same request.
      tags:
      - Member
      summary: Invite members
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiInviteUsersRsp'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request POST \\\n  -d '{\"emails\": [\"user@example.com\"], \"orgRole\": {\"rbacRole\": \"org:member\"}}' \\\n  --url 'https://iam.tidbapi.com/v1beta1/members'"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.OpenApiInviteUsersReq'
        description: The members to invite, including their email addresses and roles.
        required: true
      operationId: postMembers
      x-operation-id-source: derived
  /members/batchUpdate:
    post:
      description: Updates the organization, project, and instance roles of multiple members in a single request. You can update at most 100 members per request.
      tags:
      - Member
      summary: Batch update members
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiBatchUpdateUsersRsp'
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request POST \\\n  -d '{\"users\": [{\"userId\": \"123456\", \"orgRole\": {\"rbacRole\": \"org:member\"}}]}' \\\n  --url 'https://iam.tidbapi.com/v1beta1/members/batchUpdate'"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.openApiBatchUpdateUsersReqDoc'
        description: The members to update and the new roles to assign to each of them.
        required: true
      operationId: postMembersBatchUpdate
      x-operation-id-source: derived
  /members/{user_id}:
    delete:
      description: Removes a member from your organization. The member loses all roles within the organization.
      tags:
      - Member
      summary: Delete a member
      parameters:
      - description: The ID of the member to remove from your organization.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request DELETE \\\n  --url 'https://iam.tidbapi.com/v1beta1/members/{user_id}'"
      operationId: deleteMembersByUserId
      x-operation-id-source: derived
    patch:
      description: Updates the organization, project, and instance roles of a member. Project roles and instance roles are fully replaced when provided in the request.
      tags:
      - Member
      summary: Update a member
      parameters:
      - description: The ID of the member to update.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request PATCH \\\n  -d '{\"orgRole\": {\"rbacRole\": \"org:member\"}}' \\\n  --url 'https://iam.tidbapi.com/v1beta1/members/{user_id}'"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.openApiUpdateUserReqDoc'
        description: The new roles to assign to the member.
        required: true
      operationId: patchMembersByUserId
      x-operation-id-source: derived
  /members/{user_id}/resendInvitation:
    post:
      description: Resends the invitation email to a user who has not yet accepted the invitation.
      tags:
      - Member
      summary: Resend an invitation
      parameters:
      - description: The ID of the member whose invitation email you want to resend.
        name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
        '400':
          description: A request field is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '401':
          description: The API key cannot be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '403':
          description: The API key does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.OpenApiError'
      x-code-samples:
      - lang: curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request POST \\\n  --url 'https://iam.tidbapi.com/v1beta1/members/{user_id}/resendInvitation'"
      operationId: postMembersByUserIdResendInvitation
      x-operation-id-source: derived
components:
  schemas:
    api.OpenApiInviteUserResult:
      type: object
      properties:
        email:
          description: The email address of the invited member.
          type: string
        userId:
          description: The ID of the invited member.
          type: string
    api.OpenApiListUsersRsp:
      type: object
      properties:
        nextPageToken:
          description: The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages.
          type: string
          example: ''
        totalSize:
          description: The total number of members that match the query.
          type: integer
          example: 10
        users:
          description: The list of members returned for the current page.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiUser'
    api.openApiBatchUpdateUsersReqDoc:
      type: object
      properties:
        users:
          description: The list of members to update.
          type: array
          items:
            $ref: '#/components/schemas/api.openApiBatchUpdateUserEntryDoc'
    api.OpenApiProjectRole:
      type: object
      properties:
        rbacRole:
          description: The project-level role assigned to the member.
          type: string
          enum:
          - project:owner
          - project:dev
          - project:readonly
          - project:ctl_plane_viewer
          example: project:owner
        scopeId:
          description: The ID of the project to which the role applies.
          type: string
    api.openApiUpdateUserReqDoc:
      type: object
      properties:
        instanceRoles:
          description: The new instance-level roles to assign to the member. The existing instance roles are fully replaced when this field is provided.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiInstanceRole'
        orgRole:
          description: The new organization-level role to assign to the member.
          allOf:
          - $ref: '#/components/schemas/api.OpenApiOrgRole'
        projectRoles:
          description: The new project-level roles to assign to the member. The existing project roles are fully replaced when this field is provided.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiProjectRole'
    api.openApiBatchUpdateUserEntryDoc:
      type: object
      required:
      - userId
      properties:
        instanceRoles:
          description: The new instance-level roles to assign to the member. The existing instance roles are fully replaced when this field is provided.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiInstanceRole'
        orgRole:
          description: The new organization-level role to assign to the member.
          allOf:
          - $ref: '#/components/schemas/api.OpenApiOrgRole'
        projectRoles:
          description: The new project-level roles to assign to the member. The existing project roles are fully replaced when this field is provided.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiProjectRole'
        userId:
          description: The ID of the member to update.
          type: string
    api.OpenApiBatchUpdateUsersRsp:
      type: object
      properties:
        results:
          description: The list of update results, one for each member in the request.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiBatchUpdateUserResult'
    api.OpenApiInstanceRole:
      type: object
      properties:
        rbacRole:
          description: The instance-level role assigned to the member.
          type: string
          enum:
          - cluster:admin
          - cluster:viewer
          example: cluster:admin
        scopeId:
          description: The ID of the TiDB Cloud Starter, Essential, or Premium instance to which the role applies.
          type: string
    api.OpenApiBatchUpdateError:
      type: object
      properties:
        code:
          description: The error code returned when the member update failed.
          type: string
        message:
          description: The error message describing why the member update failed.
          type: string
    api.OpenApiUser:
      type: object
      properties:
        email:
          description: The email address of the member.
          type: string
          example: user@example.com
        firstName:
          description: The first name of the member.
          type: string
          example: John
        instanceRoles:
          description: The instance-level roles assigned to the member.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiInstanceRole'
        inviteTime:
          description: The timestamp when the member was invited, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
          type: string
          example: '2024-01-01T00:00:00Z'
        lastLoginTime:
          description: The timestamp when the member last logged in, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
          type: string
          example: '2024-01-01T00:00:00Z'
        lastName:
          description: The last name of the member.
          type: string
          example: Doe
        orgRole:
          description: The organization-level role assigned to the member.
          allOf:
          - $ref: '#/components/schemas/api.OpenApiOrgRole'
        projectRoles:
          description: The project-level roles assigned to the member.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiProjectRole'
        status:
          description: The current status of the member. `Active` indicates the member has accepted the invitation; `Pending` indicates the invitation has not yet been accepted.
          type: string
          example: Active
        userId:
          description: The ID of the member.
          type: string
          example: '123456'
    api.OpenApiError:
      type: object
      properties:
        code:
          type: string
        error: {}
        msgPrefix:
          type: string
        status:
          type: integer
    api.OpenApiOrgRole:
      type: object
      properties:
        rbacRole:
          description: The organization-level role assigned to the member.
          type: string
          enum:
          - org:owner
          - org:member
          - org:billing_admin
          - org:billing_viewer
          - org:audit_admin
          example: org:owner
        scopeId:
          description: The ID of the organization to which the role applies.
          type: string
    api.OpenApiInviteUsersRsp:
      type: object
      properties:
        message:
          description: A human-readable message describing the result of the invitation.
          type: string
        success:
          description: Indicates whether the invitation was sent successfully.
          type: boolean
        users:
          description: The list of members that were invited.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiInviteUserResult'
    api.OpenApiBatchUpdateUserResult:
      type: object
      properties:
        error:
          description: The error details when the member update failed. This field is empty when the update succeeded.
          allOf:
          - $ref: '#/components/schemas/api.OpenApiBatchUpdateError'
        success:
          description: Indicates whether the member was updated successfully.
          type: boolean
        userId:
          description: The ID of the member.
          type: string
    api.OpenApiInviteUsersReq:
      type: object
      required:
      - emails
      - orgRole
      properties:
        emails:
          description: The email addresses of the users to invite.
          type: array
          items:
            type: string
        instanceRoles:
          description: The instance-level roles to assign to the invited members.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiInstanceRole'
        orgRole:
          description: The organization-level role to assign to the invited members.
          allOf:
          - $ref: '#/components/schemas/api.OpenApiOrgRole'
        projectRoles:
          description: The project-level roles to assign to the invited members.
          type: array
          items:
            $ref: '#/components/schemas/api.OpenApiProjectRole'