Unity Catalog Credentials API

openapi: 3.2.0
info:
  title: Unity Catalog Credentials API
  version: '0.1'
servers:
- url: http://localhost:8080/api/2.1/unity-catalog
  description: Localhost reference server
tags:
- name: Credentials
paths:
  /credentials:
    post:
      tags:
      - Credentials
      operationId: createCredential
      summary: Create a credential
      description: Creates a new credential. The type of credential to be created is determined by the **purpose** field.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
      responses:
        200:
          description: The new credential was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialInfo'
    get:
      tags:
      - Credentials
      operationId: listCredentials
      summary: List credentials
      description: 'Gets an array of credentials (as __CredentialInfo__ objects).

        The array is limited to only those credentials the caller has permission to access.

        If the caller is a metastore admin, retrieval of credentials is unrestricted.

        There is no guarantee of a specific ordering of the elements in the array.'
      parameters:
      - name: max_results
        in: query
        description: "Maximum number of credentials to return.\n  - If not set, the default max page size is used.\n  - When set to a value greater than 0, the page length is the minimum of\n    this value and a server-configured value.\n  - When set to 0, the page length is set to a server-configured value\n    (recommended).\n  - When set to a value less than 0, an invalid parameter error is\n    returned.\n"
        schema:
          type: integer
          format: int32
          maximum: 1000
        required: false
      - name: page_token
        in: query
        description: Opaque pagination token to go to next page based on previous query.
        schema:
          type: string
        required: false
      - name: purpose
        in: query
        description: Return only credentials for the specified purpose.
        schema:
          $ref: '#/components/schemas/CredentialPurpose'
      responses:
        200:
          description: The credentials list was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCredentialsResponse'
  /credentials/{name}:
    parameters:
    - name: name
      in: path
      description: Name of the credential.
      required: true
      schema:
        type: string
    get:
      tags:
      - Credentials
      operationId: getCredential
      summary: Get a credential
      description: 'Gets a credential from the metastore.

        The caller must be a metastore admin, the owner of the credential, or have some permission on the credential.'
      responses:
        200:
          description: The credential was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialInfo'
    patch:
      tags:
      - Credentials
      operationId: updateCredential
      summary: Update a credential
      description: Updates a credential.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCredentialRequest'
      responses:
        200:
          description: The credential was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialInfo'
    delete:
      tags:
      - Credentials
      operationId: deleteCredential
      summary: Delete a credential
      description: Deletes a credential from the metastore. The caller must be a metastore admin or the owner of the credential.
      parameters:
      - name: force
        in: query
        description: Force deletion even if there are dependent external locations.
        required: false
        schema:
          type: boolean
      responses:
        200:
          description: The credential was successfully deleted.
          content:
            application/json:
              schema: {}
components:
  schemas:
    AwsIamRoleResponse:
      type: object
      required:
      - role_arn
      properties:
        role_arn:
          $ref: '#/components/schemas/AwsIamRoleArn'
        unity_catalog_iam_arn:
          description: The Amazon Resource Name (ARN) of the AWS IAM used by the Unity Catalog Server. This is the identity that is going to assume the AWS IAM role.
          type: string
        external_id:
          description: The external ID used in role assumption to prevent confused deputy problem.
          type: string
    AwsIamRoleRequest:
      type: object
      required:
      - role_arn
      properties:
        role_arn:
          $ref: '#/components/schemas/AwsIamRoleArn'
    AwsIamRoleArn:
      description: The Amazon Resource Name (ARN) of the AWS IAM role used to vend temporary credentials.
      type: string
    CredentialPurpose:
      type: string
      enum:
      - STORAGE
    ListCredentialsResponse:
      type: object
      properties:
        credentials:
          description: An array of credential information objects.
          type: array
          items:
            $ref: '#/components/schemas/CredentialInfo'
        next_page_token:
          type: string
          description: 'Opaque token to retrieve the next page of results. Absent if there are no more pages.

            __page_token__ should be set to this value for the next request (for the next page of results).

            '
    CreateCredentialRequest:
      type: object
      required:
      - name
      properties:
        name:
          description: The credential name. The name must be unique within the metastore.
          type: string
        comment:
          description: Comment associated with the credential.
          type: string
        aws_iam_role:
          $ref: '#/components/schemas/AwsIamRoleRequest'
        purpose:
          $ref: '#/components/schemas/CredentialPurpose'
    CredentialInfo:
      type: object
      properties:
        name:
          description: The credential name. The name must be unique within the metastore.
          type: string
        aws_iam_role:
          $ref: '#/components/schemas/AwsIamRoleResponse'
        comment:
          description: Comment associated with the credential.
          type: string
        owner:
          description: Username of current owner of credential.
          type: string
        full_name:
          description: The full name of the credential.
          type: string
        id:
          description: The unique identifier of the credential.
          type: string
        created_at:
          description: Time at which this Credential was created, in epoch milliseconds.
          type: integer
          format: int64
        created_by:
          description: Username of credential creator.
          type: string
        updated_at:
          description: Time at which this credential was last modified, in epoch milliseconds.
          type: integer
          format: int64
        updated_by:
          description: Username of user who last modified the credential.
          type: string
        purpose:
          $ref: '#/components/schemas/CredentialPurpose'
    UpdateCredentialRequest:
      type: object
      properties:
        comment:
          description: Comment associated with the credential.
          type: string
        owner:
          description: Username of current owner of credential.
          type: string
        aws_iam_role:
          $ref: '#/components/schemas/AwsIamRoleRequest'
        new_name:
          description: New name for the credential.
          type: string