openapi: 3.0.3
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken Role API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- name: Role
paths:
  /organizations/{organizationId}/role-templates:
    get:
      description: Get a list of available role templates in an Organization. A role template can be used as the basis for creating a new custom role.
      operationId: ListRoleTemplates
      parameters:
      - description: The Organization's ID.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: Filter role templates based on the scope of permissions they include.
        in: query
        name: scopeTypes
        schema:
          items:
            enum:
            - DEPLOYMENT
            - WORKSPACE
            - ORGANIZATION
            - DAG
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RoleTemplate'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Get role templates
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.get
  /organizations/{organizationId}/roles:
    get:
      description: List available user roles in an Organization.
      operationId: ListRoles
      parameters:
      - description: The Organization's ID.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: Whether to include default Astro roles in the returned list.
        in: query
        name: includeDefaultRoles
        schema:
          type: boolean
      - description: Filter the list of roles based on the scope of each role.
        in: query
        name: scopeTypes
        schema:
          items:
            enum:
            - DEPLOYMENT
            - WORKSPACE
            - ORGANIZATION
            - DAG
            type: string
          type: array
      - description: Offset for pagination.
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Limit for pagination.
        in: query
        name: limit
        schema:
          default: 20
          minimum: 0
          type: integer
      - description: Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'.
        in: query
        name: sorts
        schema:
          items:
            enum:
            - name:asc
            - name:desc
            - scopeType:asc
            - scopeType:desc
            - description:asc
            - description:desc
            - createdAt:asc
            - createdAt:desc
            - updatedAt:asc
            - updatedAt:desc
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesPaginated'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: List roles
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.get
    post:
      description: Create a custom role that you can assign to users, Teams, and API tokens.
      operationId: CreateCustomRole
      parameters:
      - description: The ID of the Organization where you want to create the custom role.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomRoleRequest'
        description: The request body for creating the custom role.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleWithPermission'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Create a custom role
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.create
  /organizations/{organizationId}/roles/{customRoleId}:
    delete:
      description: Delete a custom role.
      operationId: DeleteCustomRole
      parameters:
      - description: The ID of the Organization to which the role belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the role to delete.
        in: path
        name: customRoleId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Delete a custom role
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.delete
    post:
      description: Update the metadata or included permissions for a custom role.
      operationId: UpdateCustomRole
      parameters:
      - description: The ID of the Organization to which the role belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The custom role's ID.
        in: path
        name: customRoleId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomRoleRequest'
        description: The request body for updating the custom role.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleWithPermission'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Update custom role
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.update
  /organizations/{organizationId}/roles/{roleId}:
    get:
      description: Get details about a custom role.
      operationId: GetCustomRole
      parameters:
      - description: The ID of the Organization to which the role belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The role's ID.
        in: path
        name: roleId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleWithPermission'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Get a custom role
      tags:
      - Role
      x-permission:
      - action: organization.customRoles.get
components:
  schemas:
    Role:
      properties:
        createdAt:
          description: The time the role was created.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        id:
          description: The role's ID.
          example: cluc9tapx000901qn2xrgqdmn
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        restrictedWorkspaceIds:
          description: The IDs of Workspaces that the role is restricted to.
          example:
          - cldbvzoi20182g8odxt8ehi5i
          items:
            type: string
          type: array
        scopeType:
          description: The role's scope.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          example: DEPLOYMENT
          type: string
        updatedAt:
          description: The time the role was last updated.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        updatedBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
      required:
      - createdAt
      - createdBy
      - id
      - name
      - restrictedWorkspaceIds
      - scopeType
      - updatedAt
      - updatedBy
      type: object
    DefaultRole:
      properties:
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        permissions:
          description: The role's permissions.
          example:
          - deployment.get
          items:
            type: string
          type: array
        scopeType:
          description: The role's scope.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          - SYSTEM
          - DAG
          example: DEPLOYMENT
          type: string
      required:
      - name
      - permissions
      - scopeType
      type: object
    FieldValidationError:
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
      - code
      - field
      - message
      type: object
    RoleTemplate:
      properties:
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        permissions:
          description: The role's permissions.
          example:
          - deployment.get
          items:
            type: string
          type: array
        scopeType:
          description: The role's scope.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          - SYSTEM
          - DAG
          example: DEPLOYMENT
          type: string
      required:
      - name
      - permissions
      - scopeType
      type: object
    UpdateCustomRoleRequest:
      properties:
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        permissions:
          description: The permissions included in the role.
          example:
          - deployment.get
          items:
            type: string
          minItems: 1
          type: array
        restrictedWorkspaceIds:
          description: The IDs of the Workspaces that the role is restricted to.
          example:
          - cldbvzoi20182g8odxt8ehi5i
          items:
            type: string
          type: array
      required:
      - name
      - permissions
      type: object
    RolesPaginated:
      properties:
        defaultRoles:
          description: The list of default roles.
          items:
            $ref: '#/components/schemas/DefaultRole'
          type: array
        limit:
          description: The number of custom roles returned.
          example: 1
          type: integer
        offset:
          description: The offset of the custom roles.
          example: 1
          type: integer
        roles:
          description: The list of custom roles.
          items:
            $ref: '#/components/schemas/Role'
          type: array
        totalCount:
          description: The total number of custom roles.
          example: 1
          type: integer
      required:
      - limit
      - offset
      - roles
      - totalCount
      type: object
    RoleWithPermission:
      properties:
        createdAt:
          description: The time the role was created.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        id:
          description: The role's ID.
          example: cluc9tapx000901qn2xrgqdmn
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        permissions:
          description: The role's permissions.
          example:
          - deployment.get
          items:
            type: string
          type: array
        restrictedWorkspaceIds:
          description: The IDs of Workspaces that the role is restricted to.
          example:
          - cldbvzoi20182g8odxt8ehi5i
          items:
            type: string
          type: array
        scopeType:
          description: The role's scope.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          example: DEPLOYMENT
          type: string
        updatedAt:
          description: The time the role was last updated.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        updatedBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
      required:
      - createdAt
      - createdBy
      - id
      - name
      - permissions
      - restrictedWorkspaceIds
      - scopeType
      - updatedAt
      - updatedBy
      type: object
    CreateCustomRoleRequest:
      properties:
        description:
          description: The role's description.
          example: Subject can only view deployments.
          type: string
        name:
          description: The role's name.
          example: Deployment_Viewer
          type: string
        permissions:
          description: The permissions included in the role.
          example:
          - deployment.get
          items:
            type: string
          minItems: 1
          type: array
        restrictedWorkspaceIds:
          description: The IDs of the Workspaces that the role is restricted to.
          example:
          - cldbvzoi20182g8odxt8ehi5i
          items:
            type: string
          type: array
        scopeType:
          description: The scope of the role.
          enum:
          - DEPLOYMENT
          - DAG
          example: DEPLOYMENT
          type: string
      required:
      - name
      - permissions
      - scopeType
      type: object
    BasicSubjectProfile:
      properties:
        apiTokenName:
          description: The API token's name. Returned only when `SubjectType` is `SERVICEKEY`.
          example: my-token
          type: string
        avatarUrl:
          description: The URL for the user's profile image. Returned only when `SubjectType` is `USER`.
          example: https://avatar.url
          type: string
        fullName:
          description: The subject's full name. Returned only when `SubjectType` is `USER`.
          example: Jane Doe
          type: string
        id:
          description: The subject's ID.
          example: clm8qv74h000008mlf08scq7k
          type: string
        subjectType:
          description: The subject type.
          enum:
          - USER
          - SERVICEKEY
          example: USER
          type: string
        username:
          description: The subject's username. Returned only when `SubjectType` is `USER`.
          example: user1@company.com
          type: string
      required:
      - id
      type: object
    Error:
      properties:
        fieldErrors:
          description: 'FieldErrors carries one entry per failed request-validation constraint.

            Only present on 400 responses caused by request binding/validation.'
          items:
            $ref: '#/components/schemas/FieldValidationError'
          type: array
        message:
          type: string
        requestId:
          type: string
        statusCode:
          maximum: 600
          minimum: 400
          type: integer
      required:
      - message
      - requestId
      - statusCode
      type: object
  securitySchemes:
    JWT:
      scheme: bearer
      type: http