Coder Members API

openapi: 3.2.0
info:
  description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
  title: Coder Members API
  termsOfService: https://coder.com/legal/terms-of-service
  contact:
    name: API Support
    url: https://coder.com
    email: support@coder.com
  license:
    name: AGPL-3.0
    url: https://github.com/coder/coder/blob/main/LICENSE
  version: '2.0'
servers:
- url: /
tags:
- name: Members
paths:
  /api/v2/organizations/{organization}/members:
    get:
      tags:
      - Members
      summary: List organization members
      operationId: list-organization-members
      deprecated: true
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.OrganizationMemberWithUserData'
      security:
      - CoderSessionToken: []
  /api/v2/organizations/{organization}/members/roles:
    get:
      tags:
      - Members
      summary: Get member roles by organization
      operationId: get-member-roles-by-organization
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.AssignableRoles'
      security:
      - CoderSessionToken: []
    put:
      tags:
      - Members
      summary: Update a custom organization role
      operationId: update-a-custom-organization-role
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Role'
      security:
      - CoderSessionToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CustomRoleRequest'
        description: Update role request
        required: true
    post:
      tags:
      - Members
      summary: Insert a custom organization role
      operationId: insert-a-custom-organization-role
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Role'
      security:
      - CoderSessionToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CustomRoleRequest'
        description: Insert role request
        required: true
  /api/v2/organizations/{organization}/members/roles/{roleName}:
    delete:
      tags:
      - Members
      summary: Delete a custom organization role
      operationId: delete-a-custom-organization-role
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Role name
        name: roleName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.Role'
      security:
      - CoderSessionToken: []
  /api/v2/organizations/{organization}/members/{user}:
    get:
      tags:
      - Members
      summary: Get organization member
      operationId: get-organization-member
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      - description: User ID, name, or me
        name: user
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.OrganizationMemberWithUserData'
      security:
      - CoderSessionToken: []
    post:
      tags:
      - Members
      summary: Add organization member
      operationId: add-organization-member
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      - description: User ID, name, or me
        name: user
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.OrganizationMember'
      security:
      - CoderSessionToken: []
    delete:
      tags:
      - Members
      summary: Remove organization member
      operationId: remove-organization-member
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      - description: User ID, name, or me
        name: user
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      security:
      - CoderSessionToken: []
  /api/v2/organizations/{organization}/members/{user}/roles:
    put:
      tags:
      - Members
      summary: Assign role to organization member
      operationId: assign-role-to-organization-member
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      - description: User ID, name, or me
        name: user
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.OrganizationMember'
      security:
      - CoderSessionToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.UpdateRoles'
        description: Update roles request
        required: true
  /api/v2/organizations/{organization}/paginated-members:
    get:
      tags:
      - Members
      summary: Paginated organization members
      operationId: paginated-organization-members
      parameters:
      - description: Organization ID
        name: organization
        in: path
        required: true
        schema:
          type: string
      - description: Member search query
        name: q
        in: query
        schema:
          type: string
      - description: After ID
        name: after_id
        in: query
        schema:
          type: string
          format: uuid
      - description: Page limit, if 0 returns all members
        name: limit
        in: query
        schema:
          type: integer
      - description: Page offset
        name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.PaginatedMembersResponse'
      security:
      - CoderSessionToken: []
  /api/v2/users/roles:
    get:
      tags:
      - Members
      summary: Get site member roles
      operationId: get-site-member-roles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/codersdk.AssignableRoles'
      security:
      - CoderSessionToken: []
components:
  schemas:
    codersdk.OrganizationMember:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        organization_id:
          type: string
          format: uuid
        roles:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.SlimRole'
        updated_at:
          type: string
          format: date-time
        user_id:
          type: string
          format: uuid
    codersdk.SlimRole:
      type: object
      properties:
        display_name:
          type: string
        name:
          type: string
        organization_id:
          type: string
    codersdk.Role:
      type: object
      properties:
        display_name:
          type: string
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        organization_member_permissions:
          description: OrganizationMemberPermissions are specific for the organization in the field 'OrganizationID' above.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        organization_permissions:
          description: OrganizationPermissions are specific for the organization in the field 'OrganizationID' above.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        site_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        user_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
    codersdk.RBACAction:
      type: string
      enum:
      - application_connect
      - assign
      - create
      - create_agent
      - delete
      - delete_agent
      - read
      - read_personal
      - read_secret
      - ssh
      - share
      - unassign
      - update
      - update_agent
      - update_personal
      - use
      - view_insights
      - start
      - stop
      x-enum-varnames:
      - ActionApplicationConnect
      - ActionAssign
      - ActionCreate
      - ActionCreateAgent
      - ActionDelete
      - ActionDeleteAgent
      - ActionRead
      - ActionReadPersonal
      - ActionReadSecret
      - ActionSSH
      - ActionShare
      - ActionUnassign
      - ActionUpdate
      - ActionUpdateAgent
      - ActionUpdatePersonal
      - ActionUse
      - ActionViewInsights
      - ActionWorkspaceStart
      - ActionWorkspaceStop
    codersdk.CustomRoleRequest:
      type: object
      properties:
        display_name:
          type: string
        name:
          type: string
        organization_member_permissions:
          description: OrganizationMemberPermissions are specific to the organization the role belongs to.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        organization_permissions:
          description: OrganizationPermissions are specific to the organization the role belongs to.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        site_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        user_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
    codersdk.Permission:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/codersdk.RBACAction'
        negate:
          description: Negate makes this a negative permission
          type: boolean
        resource_type:
          $ref: '#/components/schemas/codersdk.RBACResource'
    codersdk.PaginatedMembersResponse:
      type: object
      properties:
        count:
          type: integer
        members:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.OrganizationMemberWithUserData'
    codersdk.UpdateRoles:
      type: object
      properties:
        roles:
          type: array
          items:
            type: string
    codersdk.OrganizationMemberWithUserData:
      type: object
      properties:
        avatar_url:
          type: string
        created_at:
          type: string
          format: date-time
        email:
          type: string
        global_roles:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.SlimRole'
        has_ai_seat:
          description: 'HasAISeat intentionally omits omitempty so the API always includes the

            field, even when false.'
          type: boolean
        is_service_account:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
        login_type:
          $ref: '#/components/schemas/codersdk.LoginType'
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        roles:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.SlimRole'
        status:
          enum:
          - active
          - suspended
          allOf:
          - $ref: '#/components/schemas/codersdk.UserStatus'
        updated_at:
          type: string
          format: date-time
        user_created_at:
          type: string
          format: date-time
        user_id:
          type: string
          format: uuid
        user_updated_at:
          type: string
          format: date-time
        username:
          type: string
    codersdk.UserStatus:
      type: string
      enum:
      - active
      - dormant
      - suspended
      x-enum-varnames:
      - UserStatusActive
      - UserStatusDormant
      - UserStatusSuspended
    codersdk.AssignableRoles:
      type: object
      properties:
        assignable:
          type: boolean
        built_in:
          description: BuiltIn roles are immutable
          type: boolean
        display_name:
          type: string
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        organization_member_permissions:
          description: OrganizationMemberPermissions are specific for the organization in the field 'OrganizationID' above.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        organization_permissions:
          description: OrganizationPermissions are specific for the organization in the field 'OrganizationID' above.
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        site_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
        user_permissions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Permission'
    codersdk.RBACResource:
      type: string
      enum:
      - '*'
      - ai_gateway_key
      - ai_model_price
      - ai_provider
      - ai_seat
      - aibridge_interception
      - api_key
      - assign_org_role
      - assign_role
      - audit_log
      - boundary_log
      - boundary_usage
      - chat
      - chat_model_config
      - chat_project
      - chat_project_memory
      - connection_log
      - crypto_key
      - debug_info
      - deployment_config
      - deployment_stats
      - file
      - group
      - group_member
      - idpsync_settings
      - inbox_notification
      - license
      - mcp_server_config
      - notification_message
      - notification_preference
      - notification_template
      - oauth2_app
      - oauth2_app_code_token
      - oauth2_app_secret
      - organization
      - organization_member
      - organization_skill
      - prebuilt_workspace
      - provisioner_daemon
      - provisioner_jobs
      - replicas
      - system
      - tailnet_coordinator
      - template
      - usage_event
      - user
      - user_secret
      - user_skill
      - webpush_subscription
      - workspace
      - workspace_agent_devcontainers
      - workspace_agent_resource_monitor
      - workspace_build_orchestration
      - workspace_dormant
      - workspace_proxy
      - workspace_secret
      x-enum-varnames:
      - ResourceWildcard
      - ResourceAIGatewayKey
      - ResourceAiModelPrice
      - ResourceAIProvider
      - ResourceAiSeat
      - ResourceAibridgeInterception
      - ResourceApiKey
      - ResourceAssignOrgRole
      - ResourceAssignRole
      - ResourceAuditLog
      - ResourceBoundaryLog
      - ResourceBoundaryUsage
      - ResourceChat
      - ResourceChatModelConfig
      - ResourceChatProject
      - ResourceChatProjectMemory
      - ResourceConnectionLog
      - ResourceCryptoKey
      - ResourceDebugInfo
      - ResourceDeploymentConfig
      - ResourceDeploymentStats
      - ResourceFile
      - ResourceGroup
      - ResourceGroupMember
      - ResourceIdpsyncSettings
      - ResourceInboxNotification
      - ResourceLicense
      - ResourceMCPServerConfig
      - ResourceNotificationMessage
      - ResourceNotificationPreference
      - ResourceNotificationTemplate
      - ResourceOauth2App
      - ResourceOauth2AppCodeToken
      - ResourceOauth2AppSecret
      - ResourceOrganization
      - ResourceOrganizationMember
      - ResourceOrganizationSkill
      - ResourcePrebuiltWorkspace
      - ResourceProvisionerDaemon
      - ResourceProvisionerJobs
      - ResourceReplicas
      - ResourceSystem
      - ResourceTailnetCoordinator
      - ResourceTemplate
      - ResourceUsageEvent
      - ResourceUser
      - ResourceUserSecret
      - ResourceUserSkill
      - ResourceWebpushSubscription
      - ResourceWorkspace
      - ResourceWorkspaceAgentDevcontainers
      - ResourceWorkspaceAgentResourceMonitor
      - ResourceWorkspaceBuildOrchestration
      - ResourceWorkspaceDormant
      - ResourceWorkspaceProxy
      - ResourceWorkspaceSecret
    codersdk.LoginType:
      type: string
      enum:
      - ''
      - password
      - github
      - oidc
      - token
      - none
      x-enum-varnames:
      - LoginTypeUnknown
      - LoginTypePassword
      - LoginTypeGithub
      - LoginTypeOIDC
      - LoginTypeToken
      - LoginTypeNone
  securitySchemes:
    AIGatewayKey:
      type: apiKey
      name: X-AI-Governance-Gateway-Key
      in: header
    Authorization:
      type: apiKey
      name: Authorization
      in: header
    CoderSessionToken:
      type: apiKey
      name: Coder-Session-Token
      in: header
x-provenance:
  method: harvested
  publisher: Coder
  source: https://raw.githubusercontent.com/coder/coder/main/coderd/apidoc/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)