Azure Key Vault Secrets API

openapi: 3.1.0
info:
  title: Azure Key Vault Data Plane Certificates Secrets API
  description: The Azure Key Vault data plane API for performing operations on keys, secrets, and certificates within a specific Key Vault instance. This API enables cryptographic operations, secret management, and certificate lifecycle management. All operations require OAuth 2.0 authentication via Azure Active Directory.
  version: '7.4'
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/
  license:
    name: Microsoft API License
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-apisguru-categories:
  - security
  - cloud
  x-logo:
    url: https://azure.microsoft.com/svghandler/key-vault/
servers:
- url: https://{vaultName}.vault.azure.net
  description: Azure Key Vault data plane endpoint
  variables:
    vaultName:
      description: The name of the Key Vault instance
      default: myvault
security:
- OAuth2Auth: []
tags:
- name: Secrets
  description: Operations for securely storing and managing secrets such as passwords, connection strings, and API keys.
paths:
  /secrets/{secret-name}:
    put:
      operationId: Secrets_SetSecret
      summary: Azure Key Vault Set Secret
      description: Sets a secret in a specified key vault. The SET operation adds a secret to the Azure Key Vault. If the named secret already exists, Azure Key Vault creates a new version of that secret. Requires the secrets/set permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretSetParameters'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: Secrets_DeleteSecret
      summary: Azure Key Vault Delete Secret
      description: Deletes a secret from a specified key vault. Requires the secrets/delete permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedSecretBundle'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets/{secret-name}/{secret-version}:
    get:
      operationId: Secrets_GetSecret
      summary: Azure Key Vault Get Secret
      description: Get a specified secret from a given key vault. The GET operation is applicable to any secret stored in Azure Key Vault. Requires the secrets/get permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/SecretVersionParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: Secrets_UpdateSecret
      summary: Azure Key Vault Update Secret
      description: Updates the attributes associated with a specified secret in a given key vault. Requires the secrets/set permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/SecretVersionParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretUpdateParameters'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets:
    get:
      operationId: Secrets_GetSecrets
      summary: Azure Key Vault List Secrets
      description: List secrets in a specified key vault. The Get Secrets operation is applicable to the entire vault. Requires the secrets/list permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/MaxResultsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets/{secret-name}/versions:
    get:
      operationId: Secrets_GetSecretVersions
      summary: Azure Key Vault List Secret Versions
      description: List all versions of the specified secret. Requires the secrets/list permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/MaxResultsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets/{secret-name}/backup:
    post:
      operationId: Secrets_BackupSecret
      summary: Azure Key Vault Backup Secret
      description: Requests that a backup of the specified secret be downloaded to the client. All versions of the secret will be downloaded. Requires the secrets/backup permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/SecretNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupSecretResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /secrets/restore:
    post:
      operationId: Secrets_RestoreSecret
      summary: Azure Key Vault Restore Secret
      description: Restores a backed up secret, and all its versions, to a vault. Requires the secrets/restore permission.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretRestoreParameters'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBundle'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyVaultError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SecretAttributes:
      type: object
      description: The secret management attributes.
      properties:
        enabled:
          type: boolean
          description: Determines whether the object is enabled.
          example: true
        nbf:
          type: integer
          format: unixtime
          description: Not before date in UTC.
          example: 10
        exp:
          type: integer
          format: unixtime
          description: Expiry date in UTC.
          example: 10
        created:
          type: integer
          format: unixtime
          description: Creation time in UTC.
          readOnly: true
          example: 10
        updated:
          type: integer
          format: unixtime
          description: Last updated time in UTC.
          readOnly: true
          example: 10
        recoveryLevel:
          $ref: '#/components/schemas/DeletionRecoveryLevel'
        recoverableDays:
          type: integer
          format: int32
          description: softDelete data retention days. Value should be >=7 and <=90 when softDelete enabled, otherwise 0.
          readOnly: true
          example: 10
    SecretBundle:
      type: object
      description: A secret consisting of a value, id and its attributes.
      properties:
        value:
          type: string
          description: The secret value.
          example: example_value
        id:
          type: string
          description: The secret id.
          example: abc123
        contentType:
          type: string
          description: The content type of the secret.
          example: example_value
        attributes:
          $ref: '#/components/schemas/SecretAttributes'
        tags:
          type: object
          additionalProperties:
            type: string
          description: Application specific metadata in the form of key-value pairs.
          example: example_value
        kid:
          type: string
          description: If this is a secret backing a KV certificate, then this field specifies the corresponding key backing the KV certificate.
          readOnly: true
          example: '500123'
        managed:
          type: boolean
          description: True if the secret's lifetime is managed by key vault. If this is a secret backing a certificate, then managed will be true.
          readOnly: true
          example: true
    SecretSetParameters:
      type: object
      description: The secret set parameters.
      required:
      - value
      properties:
        value:
          type: string
          description: The value of the secret.
          example: example_value
        tags:
          type: object
          additionalProperties:
            type: string
          description: Application specific metadata in the form of key-value pairs.
          example: example_value
        contentType:
          type: string
          description: Type of the secret value such as a password.
          example: example_value
        attributes:
          $ref: '#/components/schemas/SecretAttributes'
    BackupSecretResult:
      type: object
      description: The backup secret result, containing the backup blob.
      properties:
        value:
          type: string
          format: base64url
          description: The backup blob containing the backed up secret.
          readOnly: true
          example: example_value
    Error:
      type: object
      description: The key vault server error.
      properties:
        code:
          type: string
          description: The error code.
          readOnly: true
          example: example_value
        message:
          type: string
          description: The error message.
          readOnly: true
          example: example_value
        innererror:
          $ref: '#/components/schemas/Error'
      readOnly: true
    SecretItem:
      type: object
      description: The secret item containing secret metadata.
      properties:
        id:
          type: string
          description: Secret identifier.
          example: abc123
        attributes:
          $ref: '#/components/schemas/SecretAttributes'
        tags:
          type: object
          additionalProperties:
            type: string
          description: Application specific metadata in the form of key-value pairs.
          example: example_value
        contentType:
          type: string
          description: Type of the secret value such as a password.
          example: example_value
        managed:
          type: boolean
          description: True if the secret's lifetime is managed by key vault.
          readOnly: true
          example: true
    SecretListResult:
      type: object
      description: The secret list result.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/SecretItem'
          description: A list of secrets.
          readOnly: true
          example: []
        nextLink:
          type: string
          description: The URL to get the next set of secrets.
          readOnly: true
          example: example_value
    SecretUpdateParameters:
      type: object
      description: The secret update parameters.
      properties:
        contentType:
          type: string
          description: Type of the secret value such as a password.
          example: example_value
        attributes:
          $ref: '#/components/schemas/SecretAttributes'
        tags:
          type: object
          additionalProperties:
            type: string
          description: Application specific metadata in the form of key-value pairs.
          example: example_value
    KeyVaultError:
      type: object
      description: The key vault error exception.
      properties:
        error:
          $ref: '#/components/schemas/Error'
      readOnly: true
    DeletionRecoveryLevel:
      type: string
      description: Reflects the deletion recovery level currently in effect for objects in the current vault.
      enum:
      - Purgeable
      - Recoverable+Purgeable
      - Recoverable
      - Recoverable+ProtectedSubscription
      - CustomizedRecoverable+Purgeable
      - CustomizedRecoverable
      - CustomizedRecoverable+ProtectedSubscription
    DeletedSecretBundle:
      type: object
      description: A deleted secret bundle consisting of its previous id, attributes, tags, and deletion information.
      allOf:
      - $ref: '#/components/schemas/SecretBundle'
      properties:
        recoveryId:
          type: string
          description: The url of the recovery object, used to identify and recover the deleted secret.
          example: '500123'
        scheduledPurgeDate:
          type: integer
          format: unixtime
          description: The time when the secret is scheduled to be purged, in UTC.
          readOnly: true
          example: 10
        deletedDate:
          type: integer
          format: unixtime
          description: The time when the secret was deleted, in UTC.
          readOnly: true
          example: 10
    SecretRestoreParameters:
      type: object
      description: The secret restore parameters.
      required:
      - value
      properties:
        value:
          type: string
          format: base64url
          description: The backup blob associated with a secret bundle.
          example: example_value
  parameters:
    SecretVersionParameter:
      name: secret-version
      in: path
      required: true
      description: The version of the secret. This URI fragment is optional. If not specified, the latest version of the secret is returned.
      schema:
        type: string
    SecretNameParameter:
      name: secret-name
      in: path
      required: true
      description: The name of the secret.
      schema:
        type: string
        pattern: ^[0-9a-zA-Z-]+$
    ApiVersionParameter:
      name: api-version
      in: query
      required: true
      description: The API version to use for this operation.
      schema:
        type: string
        minLength: 1
        default: '7.4'
    MaxResultsParameter:
      name: maxresults
      in: query
      required: false
      description: Maximum number of results to return in a page. If not specified, the service will return up to 25 results.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 25
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      description: Azure Active Directory OAuth2 authentication. Requires an access token scoped to the Key Vault resource.
      flows:
        implicit:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
          scopes:
            https://vault.azure.net/.default: Access Azure Key Vault
externalDocs:
  description: Azure Key Vault REST API Reference
  url: https://learn.microsoft.com/en-us/rest/api/keyvault/