openapi: 3.0.3
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken ApiToken API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- description: The `apitoken` object represents a single API token within your Organization. API tokens are used to authenticate automated tools and processes to your Organization. They have varying levels of access to your resources based on their Organization, Workspace, and Deployment roles. See [Workspace API tokens](workspace-api-tokens.md) and [Organization API tokens](organization-api-tokens.md).
  name: ApiToken
paths:
  /organizations/{organizationId}/tokens:
    get:
      description: List information about all API tokens from an Organization. Filters on Workspace when Workspace ID is provided. When `includeOnlyOrganizationTokens` is `true`, only Organization API tokens are returned.
      operationId: ListApiTokens
      parameters:
      - description: The ID of the Organization to list tokens for.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Workspace to list API tokens for.
        in: query
        name: workspaceId
        schema:
          type: string
      - description: The ID of the Deployment to list API tokens for.
        in: query
        name: deploymentId
        schema:
          type: string
      - description: The ID of the DAG to list API tokens for.
        in: query
        name: dagId
        schema:
          type: string
      - description: The tags of the DAG to list API tokens for.
        in: query
        name: dagTags
        schema:
          items:
            type: string
          type: array
      - description: Whether to show only Organization API tokens.
        in: query
        name: includeOnlyOrganizationTokens
        schema:
          type: boolean
      - description: The kind of the API token to list API tokens for.
        in: query
        name: kind
        schema:
          enum:
          - STANDARD
          - DIRECT_ACCESS
          type: string
      - 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
          maximum: 1000
          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
            - description:asc
            - description:desc
            - createdAt:asc
            - createdAt:desc
            - updatedAt:asc
            - updatedAt: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 API tokens
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
    post:
      description: Create an API token. An API token is an alphanumeric token that grants programmatic access to Astro for automated workflows. An API token can be scoped to an Organization or a Workspace.
      operationId: CreateApiToken
      parameters:
      - description: The ID of the Organization where you want to create the token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiTokenRequest'
        description: The Request body for creating an 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 API token
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
  /organizations/{organizationId}/tokens/{tokenId}:
    delete:
      description: Delete an API token. When you delete an API token, make sure that no existing automation workflows are using it. After it's deleted, an API token cannot be recovered.
      operationId: DeleteApiToken
      parameters:
      - description: The ID of the Organization where you want to delete the token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The API token ID
        in: path
        name: tokenId
        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 API token
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
    get:
      description: Retrieve information about a specific API token.
      operationId: GetApiToken
      parameters:
      - description: The ID of the Organization where you want to retrieve token information.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the token that you want to retrieve data for.
        in: path
        name: tokenId
        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 API token
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
    post:
      description: Update the name and description of an API token.
      operationId: UpdateApiToken
      parameters:
      - description: The ID of the Organization where you want to update an API token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The API token you want to update.
        in: path
        name: tokenId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiTokenRequest'
        description: The request body for updating a 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: Update an API token
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
  /organizations/{organizationId}/tokens/{tokenId}/roles:
    post:
      description: Update Workspace and Organization roles for an API token.
      operationId: UpdateApiTokenRoles
      parameters:
      - description: The ID of the Organization where you want to update an API token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The API token you want to update.
        in: path
        name: tokenId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiTokenRolesRequest'
        description: The request body for updating a token.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectRoles'
          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 API token roles
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
  /organizations/{organizationId}/tokens/{tokenId}/rotate:
    post:
      description: Rotate an API token. Creates a new API token and invalidates the one you specify. Any workflows using the previous value stop working.
      operationId: RotateApiToken
      parameters:
      - description: The ID of the Organization where you want to rotate an API token.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The token to rotate
        in: path
        name: tokenId
        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: Rotate API token
      tags:
      - ApiToken
      x-permission:
      - action: organization.apiTokens.access
components:
  schemas:
    CreateApiTokenRequest:
      properties:
        description:
          description: The description for the API token.
          example: This is my API token
          type: string
        entityId:
          description: The ID of the Workspace or Deployment to which the API token is scoped. It is required if `Scope` is `WORKSPACE` or `DEPLOYMENT`.
          example: clm8pxjjw000008l23jm08hyu
          type: string
        kind:
          description: The kind of API token. Defaults to STANDARD if not specified.
          enum:
          - STANDARD
          - DIRECT_ACCESS
          example: STANDARD
          type: string
        name:
          description: The name of the API token.
          example: My token
          type: string
        role:
          description: The role of the API token.
          example: WORKSPACE_OWNER
          type: string
        scope:
          description: The scope of the API token.
          enum:
          - DEPLOYMENT
          - WORKSPACE
          - ORGANIZATION
          example: WORKSPACE
          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
      - role
      - scope
      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
    WorkspaceRole:
      properties:
        role:
          description: The role of the subject in the Workspace.
          enum:
          - WORKSPACE_OWNER
          - WORKSPACE_OPERATOR
          - WORKSPACE_AUTHOR
          - WORKSPACE_MEMBER
          - WORKSPACE_ACCESSOR
          example: WORKSPACE_MEMBER
          type: string
        workspaceId:
          description: The Workspace ID.
          example: clm8t5u4q000008jq4qoc3036
          type: string
      required:
      - role
      - workspaceId
      type: object
    DeploymentRole:
      properties:
        deploymentId:
          description: The Deployment ID.
          example: clm8t5u4q000008jq4qoc3031
          type: string
        role:
          description: The name of the role for the subject in the Deployment.
          example: DEPLOYMENT_ADMIN
          type: string
      required:
      - deploymentId
      - role
      type: object
    UpdateApiTokenRequest:
      properties:
        description:
          description: The description of the API token.
          example: This is my API token
          maxLength: 500
          type: string
        name:
          description: The name of the API token.
          example: My token
          maxLength: 256
          minLength: 1
          type: string
      required:
      - name
      type: object
    UpdateApiTokenRolesRequest:
      properties:
        roles:
          description: The roles of the API token, including DAG roles.
          items:
            $ref: '#/components/schemas/ApiTokenRole'
          minItems: 1
          type: array
      required:
      - roles
      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
    SubjectRoles:
      properties:
        dagRoles:
          description: A list of the subject's DAG roles.
          items:
            $ref: '#/components/schemas/DagRole'
          type: array
        deploymentRoles:
          description: A list of the subject's Deployment roles. Currently only for API tokens.
          items:
            $ref: '#/components/schemas/DeploymentRole'
          type: array
        organizationRole:
          description: The subject's Organization role.
          example: ORGANIZATION_OWNER,ORGANIZATION_OBSERVE_ADMIN,ORGANIZATION_OBSERVE_MEMBER,ORGANIZATION_BILLING_ADMIN,ORGANIZATION_MEMBER
          type: string
        workspaceRoles:
          description: A list of the subject's Workspace roles.
          items:
            $ref: '#/components/schemas/WorkspaceRole'
          type: array
      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
    DagRole:
      properties:
        dagId:
          description: The DAG ID. Required if Tag is not specified.
          example: my_dag
          type: string
        dagTag:
          description: The DAG tag. Required if DagId is not specified.
          example: team-a
          type: string
        deploymentId:
          description: The Deployment ID containing the DAG.
          example: clm8t5u4q000008jq4qoc3031
          type: string
        role:
          description: The role name (DAG_VIEWER, DAG_AUTHOR, or custom DAG role).
          example: DAG_VIEWER
          type: string
      required:
      - deploymentId
      - role
      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