{ "swagger": "2.0", "info": { "title": "KeyVaultClient", "description": "The key vault client performs cryptographic key operations and vault operations against the Key Vault service.", "version": "7.4" }, "x-ms-parameterized-host": { "hostTemplate": "{vaultBaseUrl}", "useSchemePrefix": false, "positionInOperation": "first", "parameters": [ { "name": "vaultBaseUrl", "description": "The vault name, for example https://myvault.vault.azure.net.", "required": true, "type": "string", "in": "path", "x-ms-skip-url-encoding": true } ] }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/secrets/{secret-name}": { "put": { "tags": [ "Secrets" ], "operationId": "SetSecret", "summary": "Sets a secret in a specified key vault.", "description": " 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. This operation requires the secrets/set permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "pattern": "^[0-9a-zA-Z-]+$", "description": "The name of the secret. The value you provide may be copied globally for the purpose of running the service. The value provided should not include personally identifiable or sensitive information." }, { "name": "parameters", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/SecretSetParameters" }, "description": "The parameters for setting the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A secret bundle containing the result of the set secret request.", "schema": { "$ref": "#/definitions/SecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "SetSecret": { "$ref": "./examples/SetSecret-example.json" } } }, "delete": { "tags": [ "Secrets" ], "operationId": "DeleteSecret", "summary": "Deletes a secret from a specified key vault.", "description": "The DELETE operation applies to any secret stored in Azure Key Vault. DELETE cannot be applied to an individual version of a secret. This operation requires the secrets/delete permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The deleted secret and information on when the secret will be deleted, and how to recover the deleted secret.", "schema": { "$ref": "#/definitions/DeletedSecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "DeleteSecret": { "$ref": "./examples/DeleteSecret-example.json" } } } }, "/secrets/{secret-name}/{secret-version}": { "patch": { "tags": [ "Secrets" ], "operationId": "UpdateSecret", "summary": "Updates the attributes associated with a specified secret in a given key vault.", "description": "The UPDATE operation changes specified attributes of an existing stored secret. Attributes that are not specified in the request are left unchanged. The value of a secret itself cannot be changed. This operation requires the secrets/set permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "name": "secret-version", "in": "path", "required": true, "type": "string", "description": "The version of the secret." }, { "name": "parameters", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/SecretUpdateParameters" }, "description": "The parameters for update secret operation." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The updated secret.", "schema": { "$ref": "#/definitions/SecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "UpdateSecret": { "$ref": "./examples/UpdateSecret-example.json" } } }, "get": { "tags": [ "Secrets" ], "operationId": "GetSecret", "summary": "Get a specified secret from a given key vault.", "description": "The GET operation is applicable to any secret stored in Azure Key Vault. This operation requires the secrets/get permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "name": "secret-version", "in": "path", "required": true, "type": "string", "description": "The version of the secret. This URI fragment is optional. If not specified, the latest version of the secret is returned." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The retrieved secret.", "schema": { "$ref": "#/definitions/SecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "GetSecret": { "$ref": "./examples/GetSecret-example.json" } } } }, "/secrets": { "get": { "tags": [ "Secrets" ], "operationId": "GetSecrets", "summary": "List secrets in a specified key vault.", "description": "The Get Secrets operation is applicable to the entire vault. However, only the base secret identifier and its attributes are provided in the response. Individual secret versions are not listed in the response. This operation requires the secrets/list permission.", "parameters": [ { "name": "maxresults", "in": "query", "required": false, "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "description": "Maximum number of results to return in a page. If not specified, the service will return up to 25 results." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A response message containing a list of secrets in the vault along with a link to the next page of secrets.", "schema": { "$ref": "#/definitions/SecretListResult" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" }, "x-ms-examples": { "GetSecrets": { "$ref": "./examples/GetSecrets-example.json" } } } }, "/secrets/{secret-name}/versions": { "get": { "tags": [ "Secrets" ], "operationId": "GetSecretVersions", "summary": "List all versions of the specified secret.", "description": "The full secret identifier and attributes are provided in the response. No values are returned for the secrets. This operations requires the secrets/list permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "name": "maxresults", "in": "query", "required": false, "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "description": "Maximum number of results to return in a page. If not specified, the service will return up to 25 results." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A response message containing a list of secrets along with a link to the next page of secrets.", "schema": { "$ref": "#/definitions/SecretListResult" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" }, "x-ms-examples": { "GetSecretVersions": { "$ref": "./examples/GetSecretVersions-example.json" } } } }, "/deletedsecrets": { "get": { "tags": [ "DeletedSecrets" ], "operationId": "GetDeletedSecrets", "summary": "Lists deleted secrets for the specified vault.", "description": "The Get Deleted Secrets operation returns the secrets that have been deleted for a vault enabled for soft-delete. This operation requires the secrets/list permission.", "parameters": [ { "name": "maxresults", "in": "query", "required": false, "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "description": "Maximum number of results to return in a page. If not specified the service will return up to 25 results." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A response message containing a list of deleted secrets in the vault, along with a link to the next page of deleted secrets.", "schema": { "$ref": "#/definitions/DeletedSecretListResult" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" }, "x-ms-examples": { "GetDeletedSecrets": { "$ref": "./examples/GetDeletedSecrets-example.json" } } } }, "/deletedsecrets/{secret-name}": { "get": { "tags": [ "DeletedSecrets" ], "operationId": "GetDeletedSecret", "summary": "Gets the specified deleted secret.", "description": "The Get Deleted Secret operation returns the specified deleted secret along with its attributes. This operation requires the secrets/get permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A secret bundle of the secret and its attributes.", "schema": { "$ref": "#/definitions/DeletedSecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "GetDeletedSecret": { "$ref": "./examples/GetDeletedSecret-example.json" } } }, "delete": { "tags": [ "DeletedSecrets" ], "operationId": "PurgeDeletedSecret", "summary": "Permanently deletes the specified secret.", "description": "The purge deleted secret operation removes the secret permanently, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the secrets/purge permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "204": { "description": "No content signaling that the secret was purged forever." }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "PurgeDeletedSecret": { "$ref": "./examples/PurgeDeletedSecret-example.json" } } } }, "/deletedsecrets/{secret-name}/recover": { "post": { "tags": [ "DeletedSecrets" ], "operationId": "RecoverDeletedSecret", "summary": "Recovers the deleted secret to the latest version.", "description": "Recovers the deleted secret in the specified vault. This operation can only be performed on a soft-delete enabled vault. This operation requires the secrets/recover permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the deleted secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "A Secret bundle of the original secret and its attributes.", "schema": { "$ref": "#/definitions/SecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "RecoverDeletedSecret": { "$ref": "./examples/RecoverDeletedSecret-example.json" } } } }, "/secrets/{secret-name}/backup": { "post": { "tags": [ "Secrets" ], "operationId": "BackupSecret", "summary": "Backs up the specified secret.", "description": "Requests that a backup of the specified secret be downloaded to the client. All versions of the secret will be downloaded. This operation requires the secrets/backup permission.", "parameters": [ { "name": "secret-name", "in": "path", "required": true, "type": "string", "description": "The name of the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "The backup blob containing the backed up secret.", "schema": { "$ref": "#/definitions/BackupSecretResult" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "BackupSecret": { "$ref": "./examples/BackupSecret-example.json" } } } }, "/secrets/restore": { "post": { "tags": [ "Secrets" ], "operationId": "RestoreSecret", "summary": "Restores a backed up secret to a vault.", "description": "Restores a backed up secret, and all its versions, to a vault. This operation requires the secrets/restore permission.", "parameters": [ { "name": "parameters", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/SecretRestoreParameters" }, "description": "The parameters to restore the secret." }, { "$ref": "common.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Restored secret bundle in the vault.", "schema": { "$ref": "#/definitions/SecretBundle" } }, "default": { "description": "Key Vault error response describing why the operation failed.", "schema": { "$ref": "common.json#/definitions/KeyVaultError" } } }, "x-ms-examples": { "RestoreSecret": { "$ref": "./examples/RestoreSecret-example.json" } } } } }, "definitions": { "SecretBundle": { "properties": { "value": { "type": "string", "description": "The secret value." }, "id": { "type": "string", "description": "The secret id." }, "contentType": { "type": "string", "description": "The content type of the secret." }, "attributes": { "$ref": "#/definitions/SecretAttributes", "description": "The secret management attributes." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application specific metadata in the form of key-value pairs." }, "kid": { "type": "string", "readOnly": true, "description": "If this is a secret backing a KV certificate, then this field specifies the corresponding key backing the KV certificate." }, "managed": { "type": "boolean", "readOnly": true, "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." } }, "description": "A secret consisting of a value, id and its attributes." }, "SecretItem": { "properties": { "id": { "type": "string", "description": "Secret identifier." }, "attributes": { "$ref": "#/definitions/SecretAttributes", "description": "The secret management attributes." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application specific metadata in the form of key-value pairs." }, "contentType": { "type": "string", "description": "Type of the secret value such as a password." }, "managed": { "type": "boolean", "readOnly": true, "description": "True if the secret's lifetime is managed by key vault. If this is a key backing a certificate, then managed will be true." } }, "description": "The secret item containing secret metadata." }, "DeletedSecretBundle": { "allOf": [ { "$ref": "#/definitions/SecretBundle" } ], "properties": { "recoveryId": { "type": "string", "description": "The url of the recovery object, used to identify and recover the deleted secret." }, "scheduledPurgeDate": { "type": "integer", "format": "unixtime", "readOnly": true, "description": "The time when the secret is scheduled to be purged, in UTC" }, "deletedDate": { "type": "integer", "format": "unixtime", "readOnly": true, "description": "The time when the secret was deleted, in UTC" } }, "description": "A Deleted Secret consisting of its previous id, attributes and its tags, as well as information on when it will be purged." }, "DeletedSecretItem": { "allOf": [ { "$ref": "#/definitions/SecretItem" } ], "properties": { "recoveryId": { "type": "string", "description": "The url of the recovery object, used to identify and recover the deleted secret." }, "scheduledPurgeDate": { "type": "integer", "format": "unixtime", "readOnly": true, "description": "The time when the secret is scheduled to be purged, in UTC" }, "deletedDate": { "type": "integer", "format": "unixtime", "readOnly": true, "description": "The time when the secret was deleted, in UTC" } }, "description": "The deleted secret item containing metadata about the deleted secret." }, "SecretAttributes": { "allOf": [ { "$ref": "common.json#/definitions/Attributes" } ], "properties": { "recoverableDays": { "type": "integer", "format": "int32", "readOnly": true, "description": "softDelete data retention days. Value should be >=7 and <=90 when softDelete enabled, otherwise 0." }, "recoveryLevel": { "type": "string", "description": "Reflects the deletion recovery level currently in effect for secrets in the current vault. If it contains 'Purgeable', the secret can be permanently deleted by a privileged user; otherwise, only the system can purge the secret, at the end of the retention interval.", "enum": [ "Purgeable", "Recoverable+Purgeable", "Recoverable", "Recoverable+ProtectedSubscription", "CustomizedRecoverable+Purgeable", "CustomizedRecoverable", "CustomizedRecoverable+ProtectedSubscription" ], "x-ms-enum": { "name": "DeletionRecoveryLevel", "modelAsString": true, "values": [ { "value": "Purgeable", "description": "Denotes a vault state in which deletion is an irreversible operation, without the possibility for recovery. This level corresponds to no protection being available against a Delete operation; the data is irretrievably lost upon accepting a Delete operation at the entity level or higher (vault, resource group, subscription etc.)" }, { "value": "Recoverable+Purgeable", "description": "Denotes a vault state in which deletion is recoverable, and which also permits immediate and permanent deletion (i.e. purge). This level guarantees the recoverability of the deleted entity during the retention interval (90 days), unless a Purge operation is requested, or the subscription is cancelled. System wil permanently delete it after 90 days, if not recovered" }, { "value": "Recoverable", "description": "Denotes a vault state in which deletion is recoverable without the possibility for immediate and permanent deletion (i.e. purge). This level guarantees the recoverability of the deleted entity during the retention interval(90 days) and while the subscription is still available. System wil permanently delete it after 90 days, if not recovered" }, { "value": "Recoverable+ProtectedSubscription", "description": "Denotes a vault and subscription state in which deletion is recoverable within retention interval (90 days), immediate and permanent deletion (i.e. purge) is not permitted, and in which the subscription itself cannot be permanently canceled. System wil permanently delete it after 90 days, if not recovered" }, { "value": "CustomizedRecoverable+Purgeable", "description": "Denotes a vault state in which deletion is recoverable, and which also permits immediate and permanent deletion (i.e. purge when 7<= SoftDeleteRetentionInDays < 90). This level guarantees the recoverability of the deleted entity during the retention interval, unless a Purge operation is requested, or the subscription is cancelled." }, { "value": "CustomizedRecoverable", "description": "Denotes a vault state in which deletion is recoverable without the possibility for immediate and permanent deletion (i.e. purge when 7<= SoftDeleteRetentionInDays < 90).This level guarantees the recoverability of the deleted entity during the retention interval and while the subscription is still available." }, { "value": "CustomizedRecoverable+ProtectedSubscription", "description": "Denotes a vault and subscription state in which deletion is recoverable, immediate and permanent deletion (i.e. purge) is not permitted, and in which the subscription itself cannot be permanently canceled when 7<= SoftDeleteRetentionInDays < 90. This level guarantees the recoverability of the deleted entity during the retention interval, and also reflects the fact that the subscription itself cannot be cancelled." } ] }, "readOnly": true, "x-nullable": false } }, "description": "The secret management attributes." }, "SecretRestoreParameters": { "properties": { "value": { "type": "string", "x-ms-client-name": "secretBundleBackup", "format": "base64url", "description": "The backup blob associated with a secret bundle." } }, "description": "The secret restore parameters.", "required": [ "value" ] }, "SecretProperties": { "properties": { "contentType": { "type": "string", "description": "The media type (MIME type)." } }, "description": "Properties of the key backing a certificate." }, "SecretSetParameters": { "properties": { "value": { "type": "string", "description": "The value of the secret." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application specific metadata in the form of key-value pairs." }, "contentType": { "type": "string", "description": "Type of the secret value such as a password." }, "attributes": { "x-ms-client-name": "secretAttributes", "$ref": "#/definitions/SecretAttributes", "description": "The secret management attributes." } }, "description": "The secret set parameters.", "required": [ "value" ] }, "SecretUpdateParameters": { "properties": { "contentType": { "type": "string", "description": "Type of the secret value such as a password." }, "attributes": { "x-ms-client-name": "secretAttributes", "$ref": "#/definitions/SecretAttributes", "description": "The secret management attributes." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Application specific metadata in the form of key-value pairs." } }, "description": "The secret update parameters." }, "SecretListResult": { "properties": { "value": { "type": "array", "items": { "$ref": "#/definitions/SecretItem" }, "readOnly": true, "description": "A response message containing a list of secrets in the key vault along with a link to the next page of secrets." }, "nextLink": { "type": "string", "readOnly": true, "description": "The URL to get the next set of secrets." } }, "description": "The secret list result." }, "DeletedSecretListResult": { "properties": { "value": { "type": "array", "items": { "$ref": "#/definitions/DeletedSecretItem" }, "readOnly": true, "description": "A response message containing a list of the deleted secrets in the vault along with a link to the next page of deleted secrets" }, "nextLink": { "type": "string", "readOnly": true, "description": "The URL to get the next set of deleted secrets." } }, "description": "The deleted secret list result" }, "BackupSecretResult": { "properties": { "value": { "type": "string", "format": "base64url", "readOnly": true, "description": "The backup blob containing the backed up secret." } }, "description": "The backup secret result, containing the backup blob." } } }