openapi: 3.0.3
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- name: AgentToken
paths:
  /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens:
    get:
      description: List Agent API Tokens.
      operationId: ListAgentTokens
      parameters:
      - description: The ID of the organization that owns the deployment you want to list tokens for.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the deployment that owns the Agent API tokens you want to list.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: The number of results to skip before returning values.
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: The maximum number of results to return.
        in: query
        name: limit
        schema:
          default: 20
          maximum: 1000
          minimum: 0
          type: integer
      - description: A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `<fieldName>:asc` or `<fieldName>:desc`.
        in: query
        name: sorts
        schema:
          items:
            enum:
            - name:asc
            - name:desc
            - description:asc
            - description:desc
            - createdAt:asc
            - createdAt:desc
            - updatedAt:asc
            - updatedAt:desc
            - createdById:asc
            - createdById:desc
            - updatedById:asc
            - updatedById:desc
            - tokenStartAt:asc
            - tokenStartAt:desc
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokensPaginated'
          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 Agent API Tokens
      tags:
      - AgentToken
      x-permission:
      - action: deployment.agentTokens.get
    post:
      description: Create an Agent API token for remote workers.
      operationId: CreateAgentToken
      parameters:
      - description: The ID of the organization that owns the deployment where you want to create the Agent API token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the deployment where you want to create the Agent API token.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentTokenRequest'
        description: The request body for creating an Agent API Token.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiToken'
          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 an Agent API token
      tags:
      - AgentToken
      x-permission:
      - action: deployment.agentTokens.create
  /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens/{agentTokenId}:
    delete:
      description: Delete an Agent API Token.
      operationId: DeleteAgentToken
      parameters:
      - description: The ID of the organization that owns the deployment where you want to delete the Agent API Token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the deployment that owns the Agent API token that you want to delete.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: The ID of the Agent API token you want to delete.
        in: path
        name: agentTokenId
        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 an Agent API Token
      tags:
      - AgentToken
      x-permission:
      - action: deployment.agentTokens.delete
    get:
      description: Get an Agent API Token.
      operationId: GetAgentToken
      parameters:
      - description: The ID of the Organization that owns the deployment where you want to retrieve Agent API token information.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the deployment where you want to retrieve Agent API token information.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: The ID of the Agent API token that you want to retrieve data for.
        in: path
        name: agentTokenId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiToken'
          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 an Agent API Token
      tags:
      - AgentToken
      x-permission:
      - action: deployment.agentTokens.get
components:
  schemas:
    CreateAgentTokenRequest:
      properties:
        description:
          description: The description for the API token.
          example: This is my API token
          type: string
        name:
          description: The name of the API token.
          example: My token
          type: string
        tokenExpiryPeriodInDays:
          description: The expiry period of the API token in days. If not specified, the token will never expire.
          example: 30
          maximum: 3650
          minimum: 1
          type: integer
      required:
      - name
      type: object
    ApiTokenRole:
      properties:
        deploymentId:
          description: Required when EntityType is DAG or TAG. The deployment containing the DAG.
          example: clm8t5u4q000008jq4qoc3031
          type: string
        entityId:
          description: The ID of the entity. For DAG roles, this is the DAG ID. For TAG roles, this is the tag value.
          example: clm8sgvai000008l794psbkdv
          type: string
        entityType:
          description: The type of the entity.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          - DAG
          - DAG_TAG
          example: WORKSPACE
          type: string
        role:
          description: The role of the API token.
          example: WORKSPACE_MEMBER
          type: string
      required:
      - entityId
      - entityType
      - role
      type: object
    FieldValidationError:
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
      - code
      - field
      - message
      type: object
    ApiToken:
      properties:
        createdAt:
          description: The time when the API token was created in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
        description:
          description: The description of the API token.
          example: my token description
          type: string
        endAt:
          description: The time when the API token expires in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        expiryPeriodInDays:
          description: The expiry period of the API token in days.
          example: 30
          type: integer
        id:
          description: The API token's ID.
          example: clm8q7f6q000008lcgyougpsk
          type: string
        kind:
          description: The kind of the API token.
          enum:
          - STANDARD
          - DIRECT_ACCESS
          example: STANDARD
          type: string
        lastRotatedAt:
          description: The time when the API token was last rotated in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        lastUsedAt:
          description: The time when the API token was last used in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        name:
          description: The name of the API token.
          example: My token
          type: string
        roles:
          description: The roles of the API token.
          items:
            $ref: '#/components/schemas/ApiTokenRole'
          type: array
        scope:
          description: The scope of the API token.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          example: WORKSPACE
          type: string
        shortToken:
          description: The short value of the API token.
          example: short-token
          type: string
        startAt:
          description: The time when the API token will become valid in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        token:
          description: The value of the API token.
          example: token
          type: string
        updatedAt:
          description: The time when the API token was last updated in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        updatedBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
      required:
      - createdAt
      - description
      - id
      - kind
      - name
      - scope
      - shortToken
      - startAt
      - updatedAt
      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
    ApiTokensPaginated:
      properties:
        limit:
          description: The limit of values in this page.
          example: 10
          type: integer
        offset:
          description: The offset of values in this page.
          example: 0
          type: integer
        tokens:
          description: The list of API tokens in this page.
          items:
            $ref: '#/components/schemas/ApiToken'
          type: array
        totalCount:
          description: The total number of API tokens.
          example: 100
          type: integer
      required:
      - limit
      - offset
      - tokens
      - totalCount
      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