openapi: 3.0.0
info:
  description: Use this REST API to manage your DataStax Astra DB organizations and perform lifecycle actions for your Astra DB databases.</br> </br> To get started, use the /v2/clientIdSecrets endpoints to create a token to authenticate your API calls.
  version: 2.3.0
  title: Astra DevOps Access List API
  contact:
    email: ad-astra@datastax.com
servers:
- url: https://api.astra.datastax.com/
security:
- BearerAuth:
  - org-admin
  - org-db-create
  - org-db-terminate
  - org-db-view
  - org-db-expand
  - org-db-suspend
  - org-db-addpeering
  - org-db-readpeering
  - db-keyspace-create
  - db-cql
  - accesslist-write
  - accesslist-read
  - db-manage-privateendpoint
  - db-manage-telemetry
  - db-manage-backupconfiguration
tags:
- name: Access List
  description: View, create, modify, or delete the IP access list for an Astra database.
paths:
  /v2/access-lists:
    get:
      tags:
      - Access List
      summary: Get all access lists for an organization
      security:
      - BearerAuth:
        - accesslist-read
      operationId: GetAllAccessListsForOrganization
      responses:
        '200':
          description: Access lists for an organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/databases/{databaseID}/access-list:
    get:
      tags:
      - Access List
      summary: Get the access list for a database
      security:
      - BearerAuth:
        - accesslist-read
      operationId: GetAccessListForDatabase
      parameters:
      - $ref: '#/components/parameters/DatabaseIdParam'
      responses:
        '200':
          description: Access list for a database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
      - Access List
      summary: Upsert the access list for a database. This endpoint replaces the entire access list with what is present in the request body.
      security:
      - BearerAuth:
        - accesslist-write
      operationId: UpsertAccessListForDatabase
      parameters:
      - $ref: '#/components/parameters/DatabaseIdParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessListRequest'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
      - Access List
      summary: Add addresses to the access list for a database
      security:
      - BearerAuth:
        - accesslist-write
      operationId: AddAddressesToAccessListForDatabase
      parameters:
      - $ref: '#/components/parameters/DatabaseIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddressRequest'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    patch:
      tags:
      - Access List
      summary: Update the access list for a database. This endpoint updates existing fields in the access list if they exist
      security:
      - BearerAuth:
        - accesslist-write
      operationId: UpdateAccessListForDatabase
      parameters:
      - $ref: '#/components/parameters/DatabaseIdParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessListRequest'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
      - Access List
      summary: Delete a list of addresses or the access list for a database. If the addresses query parameter is not present it will delete the entire access list. If the addresses query parameter is present it will delete only the given addresses from the access list
      security:
      - BearerAuth:
        - accesslist-write
      operationId: DeleteAddressesOrAccessListForDatabase
      parameters:
      - $ref: '#/components/parameters/DatabaseIdParam'
      - $ref: '#/components/parameters/AddressesQueryParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/access-list/validate:
    post:
      tags:
      - Access List
      summary: Validate the structure of an access list
      operationId: ValidateAccessList
      responses:
        '200':
          description: Access lists for an organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/access-list/template:
    post:
      tags:
      - Access List
      summary: Get a template of an access list
      operationId: GetAccessListTemplate
      responses:
        '200':
          description: Access lists for an organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessListRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    AddressRequest:
      type: object
      description: The model used to build an address for an access list
      required:
      - address
      - enabled
      - description
      properties:
        address:
          pattern: ^([0-9]{1,3}\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$
          type: string
          description: The address (ip address and subnet mask in CIDR notation) of the address to allow
          example: 137.187.23.0/24
        enabled:
          type: boolean
          description: The indication if the access address is enabled or not
          example: true
        description:
          type: string
          description: Description of this addresses use
          example: This address allows the database connections from the prod environment
    AccessListConfigurations:
      required:
      - accessListEnabled
      type: object
      properties:
        accessListEnabled:
          type: boolean
    AccessListResponse:
      type: object
      description: The response for a requested access list
      properties:
        organizationId:
          type: string
          description: The unique identifier of the organization
          format: uuid
          example: 303a3598-0905-4b5d-9db2-4bf2f9790973
        databaseId:
          type: string
          description: The unique identifier of the database
          format: uuid
          example: 8fbcfe1d-56fa-4ed0-9aff-f57029feef1b
        addresses:
          type: array
          description: A listing of the allowed addresses
          items:
            $ref: '#/components/schemas/AddressResponse'
        configurations:
          $ref: '#/components/schemas/AccessListConfigurations'
    AddressResponse:
      type: object
      description: The response for a requested address in an access list
      properties:
        address:
          pattern: ^([0-9]{1,3}\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$
          type: string
          description: The address (ip address and subnet mask in CIDR notation) of the address to allow
          example: 137.187.23.0/24
        enabled:
          type: boolean
          description: The indication if the access address is enabled or not
          example: true
        description:
          type: string
          description: Description of this addresses use
          example: This address allows the database connections from the prod environment
        lastUpdateDateTime:
          type: string
          description: The last update date/time for the access list
          format: date-time
          example: '2021-01-21T17:32:28Z'
    Error:
      description: ModelError information that is returned to users
      type: object
      required:
      - id
      - message
      properties:
        ID:
          type: integer
          example: 123
          description: API specific error code
        message:
          type: string
          example: Something is broken
          description: User-friendly description of error
    AccessListRequest:
      type: object
      description: The model used to build an access list
      properties:
        addresses:
          type: array
          description: A listing of the allowed addresses
          items:
            $ref: '#/components/schemas/AddressRequest'
        configurations:
          $ref: '#/components/schemas/AccessListConfigurations'
    ValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
        validationFailures:
          type: array
          items:
            type: string
      description: The response for validation checks
    Errors:
      description: Errors is a collection of individual Error objects
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  parameters:
    AddressesQueryParam:
      in: query
      name: addresses
      required: false
      schema:
        type: array
        items:
          type: string
      description: Array of addresses
    DatabaseIdParam:
      in: path
      name: databaseID
      required: true
      description: String representation of the database ID
      schema:
        type: string
  responses:
    ServerError:
      description: A server error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    Unauthorized:
      description: The user is unauthorized to perform the operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    Forbidden:
      description: The user is forbidden to perform the operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFound:
      description: The specified database was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NoContent:
      description: The request succeeded and no content is returned in response body
  securitySchemes:
    BearerAuth:
      description: An application token must be passed in header in order to access the API. https://docs.datastax.com/en/astra-db-serverless/administration/manage-application-tokens.html
      type: http
      scheme: bearer