canonical: https://jentic.com/apis/azure.com/keyvaultclient

# Microsoft Azure KeyVaultClient

Jentic publishes the only available OpenAPI specification for the Azure Key Vault data plane (7.0-preview), keeping it validated and agent-ready. The KeyVaultClient performs cryptographic key operations and secret, certificate, and storage account credential operations against a vault host such as https://myvault.vault.azure.net. It exposes 78 endpoints to manage keys, secrets, certificates and their policies, soft-deleted resources and recovery, certificate issuers and contacts, and storage account access definitions.

## For AI agents

Manage and use Azure Key Vault keys, secrets, and certificates including sign, encrypt, wrap, backup, restore, and soft-delete recovery against a specific vault host.

## Scope

Does not handle vault provisioning, RBAC role assignment, or network ACL configuration - use for Key Vault data-plane key, secret, and certificate operations only.

## Capabilities

- Create, import, and rotate cryptographic keys with sign, verify, encrypt, decrypt, wrap, and unwrap operations
- Set, get, and version secrets stored in a vault
- Issue, import, merge, and renew X.509 certificates with policy-driven lifecycles
- Configure certificate issuers and contact addresses for renewal notifications
- Back up keys, secrets, and certificates and restore them into the same or another vault
- Recover or purge soft-deleted keys, secrets, and certificates
- Manage storage account credentials and SAS definitions surfaced through the vault

## Use cases

### Workload Secret Retrieval at Runtime

Application workloads fetch database connection strings and third-party API keys from Key Vault at runtime via /secrets/{secret-name} rather than baking them into config files. The vault returns the value over TLS scoped to the AAD identity making the call. This is the standard pattern for credential-free Azure deployments and integrates naturally with managed identity tokens from IMDS.

Example prompt: GET https://acme-vault.vault.azure.net/secrets/db-connection-string?api-version=7.0 and return the value field.

### HSM-Backed Cryptographic Operations

Security-sensitive workloads keep private keys in Key Vault and call /keys/{key-name}/sign and /keys/{key-name}/wrapkey to sign payloads or wrap data encryption keys without exporting the private material. The vault performs the operation server-side, so the key never leaves the HSM boundary. This is the foundation for envelope encryption and signed-token issuance from server workloads.

Example prompt: POST to /keys/signing-key/sign with alg=RS256 and the SHA-256 hash of the payload, then return the resulting signature.

### Certificate Issuance and Renewal

Platform teams issue X.509 certificates from Key Vault by configuring an issuer (e.g. DigiCert), defining a certificate policy, and POSTing /certificates/{certificate-name}/create. Key Vault tracks pending operations and merges the signed certificate back when the issuer responds. The same flow drives automatic renewal as policies hit their renewal window.

Example prompt: POST a certificate creation with issuerName 'DigiCert' and subject 'CN=api.acme.com' to /certificates/api-acme-com/create.

### Soft-Delete Recovery and Backup Hygiene

Operators recover accidentally deleted keys, secrets, or certificates by walking /deletedkeys, /deletedsecrets, and /deletedcertificates and POSTing the recover endpoint on the affected resource. For compliant backup hygiene the same teams call backup endpoints to export blobs that can be restored into a paired vault. This is essential for production vaults that hold critical credentials.

Example prompt: List all deletedsecrets in the vault and POST recover on any whose name starts with 'prod-'.

### Agent-Driven Secret Access via Jentic

An AI agent can fetch secrets, sign payloads, and rotate certificates in Key Vault through Jentic without holding raw AAD credentials or vault access tokens. The agent searches Jentic for 'get a secret from azure key vault', loads the operation schema, and executes against the target vault host. Jentic's your Jentic One instance injects a scoped bearer token for the vault audience.

Example prompt: Use the Jentic MCP tool azure_keyvault_get_secret to fetch the value of secret 'stripe-key' from vault https://acme-vault.vault.azure.net.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /secrets/{secret-name} | Get the latest version of a secret |
| PUT | /secrets/{secret-name} | Set or update a secret value |
| POST | /keys/{key-name}/sign | Sign a payload with a key |
| POST | /keys/{key-name}/wrapkey | Wrap a symmetric key with a vault key |
| POST | /certificates/{certificate-name}/create | Create a new certificate via the configured issuer policy |
| POST | /keys/{key-name}/backup | Back up a key as a portable blob |
| POST | /deletedsecrets/{secret-name}/recover | Recover a soft-deleted secret |

## Key resources

- **Keys** — Cryptographic keys with create, import, rotate, sign, verify, encrypt, decrypt, wrap, and unwrap operations
- **Secrets** — Versioned key-value secrets with set, get, list, and update operations
- **Certificates** — X.509 certificates with policy, issuer, pending merge, and version management
- **DeletedKeys / DeletedSecrets / DeletedCertificates** — Soft-deleted resources available for recovery or purge
- **CertificateIssuers** — Configured issuers (e.g. DigiCert) used to source signed certificates
- **CertificateContacts** — Email contacts notified for certificate lifecycle events
- **StorageAccounts / SasDefinitions** — Managed storage account credentials and SAS definitions surfaced through the vault

## Why Jentic

- **Setup:** Wiring the Key Vault data plane by hand means registering an Azure AD app for the vault.azure.net audience, negotiating OAuth 2.0 bearer tokens, and pointing every call at the per-vault {vaultBaseUrl} host rather than the ARM control plane. Through Jentic you install once, import KeyVaultClient from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** This API puts the secret, key, and certificate name in the URL path (/secrets/{secret-name}, /keys/{key-name}/sign), so a rule can pin your agent to specific objects: it can read a secret and sign or wrap with a named key. You choose the operations it may call, so writing a secret, creating a certificate, or backing up a key is not included unless you add it.
- **Credential handling:** Your Azure AD credential for the vault.azure.net audience is stored once, encrypted, by your own Jentic One instance and injected at execution time, and secret values returned from the vault stay out of the agent's prompt, logs, or context beyond the invocation.
- **Discovery method:** Agents search Jentic by intent such as 'get a secret from Azure Key Vault' or 'sign a payload with a Key Vault key', and Jentic returns the matching Key Vault operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Azure Instance Metadata Service** — IMDS issues the managed identity token used to authenticate against Key Vault from inside an Azure VM.
- **Azure IoT Hub** — IoT Hub workloads commonly fetch device-side credentials and CA private keys from Key Vault.
- **Azure IoT Device Provisioning Service** — DPS verification flows benefit from CA private keys held in Key Vault rather than on disk.

## FAQ

### Why is there no official OpenAPI spec for KeyVaultClient?

Microsoft documents the Key Vault data plane as a REST API but does not publish a maintained OpenAPI 3 specification for it. Jentic generates and maintains this spec so that AI agents and developers can call KeyVaultClient via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the KeyVaultClient use?

The data plane requires an Azure Active Directory OAuth 2.0 bearer token whose audience is https://vault.azure.net. Through Jentic the AAD client secret or refresh token is held in the your Jentic One instance and a vault-scoped bearer token is injected per call so the agent never sees raw secrets.

### Can I sign a payload without exporting the key?

Yes. POST to /keys/{key-name}/sign with the algorithm (e.g. RS256) and the digest in the request body. The vault performs the signing inside its HSM boundary and returns only the signature, so the private key never leaves the vault.

### What are the rate limits for KeyVaultClient?

Key Vault enforces per-vault transaction quotas - typically 2,000 transactions every 10 seconds for HSM keys and higher for software-protected keys, with limits surfaced via 429 responses including a Retry-After header. Cryptographic operations and key management operations have separate buckets, so balance batch-signing carefully.

### How do I fetch a secret through Jentic?

Run pip install jentic, then search Jentic with 'get a secret from azure key vault', load the get-secret operation, and execute with the vault host and secret-name. Jentic returns the secret bundle including value, contentType, and tags.

### Can I recover a deleted secret with this API?

Yes - when soft delete is enabled on the vault. List candidates via GET /deletedsecrets, then POST /deletedsecrets/{secret-name}/recover to restore the secret to its prior version. Without soft delete the secret is permanently gone, so verify the vault property before relying on this flow.

### Can I limit what my agent is allowed to do with the Microsoft Azure Key Vault API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which Key Vault operations and credentials the agent may use. Since this API puts the object name in the URL path, such as /secrets/{secret-name} and /keys/{key-name}/sign, you can pin the agent to specific objects and to read-only actions like getting a secret or signing with a named key. Writing a secret, creating a certificate, or backing up a key stays off limits unless you explicitly grant those operations.