Credential vault
How the platform stores secrets you give it, how rotation works, and what metadata you can inventory without reading them.
The credential vault holds the secrets the platform stores for you: provider API keys and OAuth tokens, OAuth client secrets, MCP server auth, HTTP callback secrets, hosted code secrets, channel credentials, and webhook signing secrets. No API returns a secret value after you submit it. The platform generates webhook signing secrets and returns each one only in the create or rotate response. You manage a secret through the resource that owns it, and you can list metadata about every stored secret in an environment.
How secrets are stored
Each independently rotatable secret is one vault entry. The vault uses envelope encryption:
- For each write, the platform asks the cloud key management service (KMS) for a new AES-256 data key.
- It encrypts the secret with AES-256-GCM in application code and stores the ciphertext with the encrypted data key.
- An encryption context binds the ciphertext to its organization, project, environment, owner type, owner ID, purpose, and credential ID. Decryption with any other context fails.
Owner records never hold the secret. They hold a reference of the form { "store": "dynamodb-kms", "credentialId", "generation" }.
Generations and rotation
A vault entry starts at generation 0. Each rotation writes generation n + 1 and requires the expected current generation, so two concurrent rotations cannot both succeed. Work that read a reference pins its generation, and a read with a stale generation fails. Revoking an entry marks it revoked, and reads of a revoked entry fail.
You never call the vault directly. Rotate and revoke secrets through their owners:
| Owner type | Purpose | Rotate or revoke with |
|---|---|---|
provider-connection | provider-oauth-token (OAuth) or provider-api | deployments credential rotate, deployments connection revoke |
provider-application | provider-oauth-client-secret | deployments oauth-app rotate, deployments oauth-app archive |
mcp-server | mcp-server-auth | deployments mcp-server update, deployments mcp-server archive |
tool-adapter | extension-callback-auth or hosted-code-secrets | deployments extension update, deployments extension archive |
webhook-endpoint | webhook-signing | See Webhooks. |
channel-binding | channel-runtime | See Channels. |
Archiving an MCP server, OAuth app, extension tool, or webhook endpoint revokes its secret. Disconnecting a provider connection revokes its token or key. Archiving a channel binding keeps its credential until you revoke the binding credential.
Inventory secrets without reading them
GET /v1/credential-references lists every vault reference that a durable owner holds in the environment named by x-deployments-environment. The response never contains secret values, ciphertext, data keys, or hashes. The API builds it from owner records alone.
| Field | Meaning |
|---|---|
ownerType, ownerId, ownerName, ownerStatus | The resource that holds the secret. |
providerKey | Present for provider applications, connections, provider-backed tools, and channel bindings. |
purpose | What the secret is for (table above). |
credentialId, generation, store | The vault reference. store is always dynamodb-kms. |
status | revoked when the owner's lifecycle revoked the entry, otherwise active. |
expiresAt | The access-token expiry of an OAuth connection. |
secretNames | The declared secret names of a hosted code tool. |
createdAt, updatedAt | The owner record's timestamps. |
Filter with ownerType. Results come in owner-type order, then by owner ID. limit takes 1 to 100. A page can hold fewer items than limit when owners without a secret fill it, so keep following nextCursor until it is null. A cursor works only with the environment and filter that produced it. Short-lived owners such as OAuth authorization attempts and stream sessions are not listed.
The inventory needs the secrets:read capability. It is separate from providers:read and tools:read, so you can grant one without the other.
Use it
List the secrets held by tools in the current environment:
deployments credential-reference list --owner-type tool-adapterThe same list from the SDK:
import { createClient, createConfig, listCredentialReferences } from "@deployments-ai/sdk";
const client = createClient(
createConfig({
baseUrl: "https://api.example.com",
headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
}),
);
const { data, error } = await listCredentialReferences({
client,
headers: { "x-deployments-environment": "env_123" },
query: { ownerType: "provider-connection" },
});Rotate a static provider credential from a file so the secret stays out of shell history:
deployments credential rotate $CONNECTION_ID --expected-version 3 --credential-file ./new-key.json