Coder Authorization 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 Agents Authorization 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: https://{coderHost}/api/v2
  description: Coder instance
  variables:
    coderHost:
      default: coder.example.com
      description: Your Coder deployment hostname
security:
- CoderSessionToken: []
tags:
- name: Authorization
paths:
  /api/v2/auth/scopes:
    get:
      operationId: list-api-key-scopes
      summary: List API key scopes
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.ExternalAPIKeyScopes'
  /api/v2/authcheck:
    post:
      operationId: check-authorization
      summary: Check authorization
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.AuthorizationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.AuthorizationResponse'
  /api/v2/users/login:
    post:
      operationId: log-in-user
      summary: Log in user
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.LoginWithPasswordRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.LoginWithPasswordResponse'
  /api/v2/users/otp/change-password:
    post:
      operationId: change-password-with-a-one-time-passcode
      summary: Change password with a one-time passcode
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.ChangePasswordWithOneTimePasscodeRequest'
      responses:
        '204':
          description: No Content
  /api/v2/users/otp/request:
    post:
      operationId: request-one-time-passcode
      summary: Request one-time passcode
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.RequestOneTimePasscodeRequest'
      responses:
        '204':
          description: No Content
  /api/v2/users/validate-password:
    post:
      operationId: validate-user-password
      summary: Validate user password
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.ValidateUserPasswordRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.ValidateUserPasswordResponse'
  /api/v2/users/{user}/convert-login:
    post:
      operationId: convert-user-from-password-to-oauth-authentication
      summary: Convert user from password to oauth authentication
      tags:
      - Authorization
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: User ID, name, or me
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.ConvertLoginRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.OAuthConversionResponse'
components:
  schemas:
    codersdk.AuthorizationRequest:
      type: object
      properties:
        checks:
          type: object
          description: 'Checks is a map keyed with an arbitrary string to a permission check.

            The key can be any string that is helpful to the caller, and allows

            multiple permission checks to be run in a single request.

            The key ensures that each permission check has the same key in the

            response.'
          additionalProperties:
            $ref: '#/components/schemas/codersdk.AuthorizationCheck'
    codersdk.LoginWithPasswordRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
      required:
      - email
      - password
    codersdk.RBACAction:
      type: string
      enum:
      - application_connect
      - assign
      - create
      - create_agent
      - delete
      - delete_agent
      - read
      - read_personal
      - ssh
      - share
      - unassign
      - update
      - update_agent
      - update_personal
      - use
      - view_insights
      - start
      - stop
    codersdk.ConvertLoginRequest:
      type: object
      properties:
        password:
          type: string
        to_type:
          description: ToType is the login type to convert to.
          allOf:
          - $ref: '#/components/schemas/codersdk.LoginType'
      required:
      - password
      - to_type
    codersdk.ExternalAPIKeyScopes:
      type: object
      properties:
        external:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.APIKeyScope'
    codersdk.AuthorizationResponse:
      type: object
      additionalProperties:
        type: boolean
    codersdk.LoginType:
      type: string
      enum:
      - ''
      - password
      - github
      - oidc
      - token
      - none
    codersdk.AuthorizationObject:
      type: object
      description: 'AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.'
      properties:
        any_org:
          type: boolean
          description: 'AnyOrgOwner (optional) will disregard the org_owner when checking for permissions.

            This cannot be set to true if the OrganizationID is set.'
        organization_id:
          type: string
          description: OrganizationID (optional) adds the set constraint to all resources owned by a given organization.
        owner_id:
          type: string
          description: OwnerID (optional) adds the set constraint to all resources owned by a given user.
        resource_id:
          type: string
          description: 'ResourceID (optional) reduces the set to a singular resource. This assigns

            a resource ID to the resource type, eg: a single workspace.

            The rbac library will not fetch the resource from the database, so if you

            are using this option, you should also set the owner ID and organization ID

            if possible. Be as specific as possible using all the fields relevant.'
        resource_type:
          description: 'ResourceType is the name of the resource.

            `./coderd/rbac/object.go` has the list of valid resource types.'
          allOf:
          - $ref: '#/components/schemas/codersdk.RBACResource'
    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
      - connection_log
      - crypto_key
      - debug_info
      - deployment_config
      - deployment_stats
      - file
      - group
      - group_member
      - idpsync_settings
      - inbox_notification
      - license
      - notification_message
      - notification_preference
      - notification_template
      - oauth2_app
      - oauth2_app_code_token
      - oauth2_app_secret
      - organization
      - organization_member
      - prebuilt_workspace
      - provisioner_daemon
      - provisioner_jobs
      - replicas
      - system
      - tailnet_coordinator
      - task
      - template
      - usage_event
      - user
      - user_secret
      - user_skill
      - webpush_subscription
      - workspace
      - workspace_agent_devcontainers
      - workspace_agent_resource_monitor
      - workspace_dormant
      - workspace_proxy
    codersdk.ChangePasswordWithOneTimePasscodeRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        one_time_passcode:
          type: string
        password:
          type: string
      required:
      - email
      - one_time_passcode
      - password
    codersdk.AuthorizationCheck:
      type: object
      description: AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.
      properties:
        action:
          enum:
          - create
          - read
          - update
          - delete
          allOf:
          - $ref: '#/components/schemas/codersdk.RBACAction'
        object:
          description: 'Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, and all workspaces across the entire product.

            When defining an object, use the most specific language when possible to

            produce the smallest set. Meaning to set as many fields on ''Object'' as

            you can. Example, if you want to check if you can update all workspaces

            owned by ''me'', try to also add an ''OrganizationID'' to the settings.

            Omitting the ''OrganizationID'' could produce the incorrect value, as

            workspaces have both `user` and `organization` owners.'
          allOf:
          - $ref: '#/components/schemas/codersdk.AuthorizationObject'
    codersdk.LoginWithPasswordResponse:
      type: object
      properties:
        session_token:
          type: string
      required:
      - session_token
    codersdk.RequestOneTimePasscodeRequest:
      type: object
      properties:
        email:
          type: string
          format: email
      required:
      - email
    codersdk.APIKeyScope:
      type: string
      enum:
      - all
      - application_connect
      - ai_gateway_key:*
      - ai_gateway_key:create
      - ai_gateway_key:delete
      - ai_gateway_key:read
      - ai_model_price:*
      - ai_model_price:read
      - ai_model_price:update
      - ai_provider:*
      - ai_provider:create
      - ai_provider:delete
      - ai_provider:read
      - ai_provider:update
      - ai_seat:*
      - ai_seat:create
      - ai_seat:read
      - aibridge_interception:*
      - aibridge_interception:create
      - aibridge_interception:read
      - aibridge_interception:update
      - api_key:*
      - api_key:create
      - api_key:delete
      - api_key:read
      - api_key:update
      - assign_org_role:*
      - assign_org_role:assign
      - assign_org_role:create
      - assign_org_role:delete
      - assign_org_role:read
      - assign_org_role:unassign
      - assign_org_role:update
      - assign_role:*
      - assign_role:assign
      - assign_role:read
      - assign_role:unassign
      - audit_log:*
      - audit_log:create
      - audit_log:read
      - boundary_log:*
      - boundary_log:create
      - boundary_log:delete
      - boundary_log:read
      - boundary_usage:*
      - boundary_usage:delete
      - boundary_usage:read
      - boundary_usage:update
      - chat:*
      - chat:create
      - chat:delete
      - chat:read
      - chat:share
      - chat:update
      - coder:all
      - coder:apikeys.manage_self
      - coder:application_connect
      - coder:templates.author
      - coder:templates.build
      - coder:workspaces.access
      - coder:workspaces.create
      - coder:workspaces.delete
      - coder:workspaces.operate
      - connection_log:*
      - connection_log:read
      - connection_log:update
      - crypto_key:*
      - crypto_key:create
      - crypto_key:delete
      - crypto_key:read
      - crypto_key:update
      - debug_info:*
      - debug_info:read
      - deployment_config:*
      - deployment_config:read
      - deployment_config:update
      - deployment_stats:*
      - deployment_stats:read
      - file:*
      - file:create
      - file:read
      - group:*
      - group:create
      - group:delete
      - group:read
      - group:update
      - group_member:*
      - group_member:read
      - idpsync_settings:*
      - idpsync_settings:read
      - idpsync_settings:update
      - inbox_notification:*
      - inbox_notification:create
      - inbox_notification:read
      - inbox_notification:update
      - license:*
      - license:create
      - license:delete
      - license:read
      - notification_message:*
      - notification_message:create
      - notification_message:delete
      - notification_message:read
      - notification_message:update
      - notification_preference:*
      - notification_preference:read
      - notification_preference:update
      - notification_template:*
      - notification_template:read
      - notification_template:update
      - oauth2_app:*
      - oauth2_app:create
      - oauth2_app:delete
      - oauth2_app:read
      - oauth2_app:update
      - oauth2_app_code_token:*
      - oauth2_app_code_token:create
      - oauth2_app_code_token:delete
      - oauth2_app_code_token:read
      - oauth2_app_secret:*
      - oauth2_app_secret:create
      - oauth2_app_secret:delete
      - oauth2_app_secret:read
      - oauth2_app_secret:update
      - organization:*
      - organization:create
      - organization:delete
      - organization:read
      - organization:update
      - organization_member:*
      - organization_member:create
      - organization_member:delete
      - organization_member:read
      - organization_member:update
      - prebuilt_workspace:*
      - prebuilt_workspace:delete
      - prebuilt_workspace:update
      - provisioner_daemon:*
      - provisioner_daemon:create
      - provisioner_daemon:delete
      - provisioner_daemon:read
      - provisioner_daemon:update
      - provisioner_jobs:*
      - provisioner_jobs:create
      - provisioner_jobs:read
      - provisioner_jobs:update
      - replicas:*
      - replicas:read
      - system:*
      - system:create
      - system:delete
      - system:read
      - system:update
      - tailnet_coordinator:*
      - tailnet_coordinator:create
      - tailnet_coordinator:delete
      - tailnet_coordinator:read
      - tailnet_coordinator:update
      - task:*
      - task:create
      - task:delete
      - task:read
      - task:update
      - template:*
      - template:create
      - template:delete
      - template:read
      - template:update
      - template:use
      - template:view_insights
      - usage_event:*
      - usage_event:create
      - usage_event:read
      - usage_event:update
      - user:*
      - user:create
      - user:delete
      - user:read
      - user:read_personal
      - user:update
      - user:update_personal
      - user_secret:*
      - user_secret:create
      - user_secret:delete
      - user_secret:read
      - user_secret:update
      - user_skill:*
      - user_skill:create
      - user_skill:delete
      - user_skill:read
      - user_skill:update
      - webpush_subscription:*
      - webpush_subscription:create
      - webpush_subscription:delete
      - webpush_subscription:read
      - workspace:*
      - workspace:application_connect
      - workspace:create
      - workspace:create_agent
      - workspace:delete
      - workspace:delete_agent
      - workspace:read
      - workspace:share
      - workspace:ssh
      - workspace:start
      - workspace:stop
      - workspace:update
      - workspace:update_agent
      - workspace_agent_devcontainers:*
      - workspace_agent_devcontainers:create
      - workspace_agent_resource_monitor:*
      - workspace_agent_resource_monitor:create
      - workspace_agent_resource_monitor:read
      - workspace_agent_resource_monitor:update
      - workspace_dormant:*
      - workspace_dormant:application_connect
      - workspace_dormant:create
      - workspace_dormant:create_agent
      - workspace_dormant:delete
      - workspace_dormant:delete_agent
      - workspace_dormant:read
      - workspace_dormant:share
      - workspace_dormant:ssh
      - workspace_dormant:start
      - workspace_dormant:stop
      - workspace_dormant:update
      - workspace_dormant:update_agent
      - workspace_proxy:*
      - workspace_proxy:create
      - workspace_proxy:delete
      - workspace_proxy:read
      - workspace_proxy:update
    codersdk.ValidateUserPasswordRequest:
      type: object
      properties:
        password:
          type: string
      required:
      - password
    codersdk.ValidateUserPasswordResponse:
      type: object
      properties:
        details:
          type: string
        valid:
          type: boolean
    codersdk.OAuthConversionResponse:
      type: object
      properties:
        expires_at:
          type: string
          format: date-time
        state_string:
          type: string
        to_type:
          $ref: '#/components/schemas/codersdk.LoginType'
        user_id:
          type: string
          format: uuid
  securitySchemes:
    CoderSessionToken:
      type: apiKey
      in: header
      name: Coder-Session-Token