Deployments.ai Docs
Platform

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:

  1. For each write, the platform asks the cloud key management service (KMS) for a new AES-256 data key.
  2. It encrypts the secret with AES-256-GCM in application code and stores the ciphertext with the encrypted data key.
  3. 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 typePurposeRotate or revoke with
provider-connectionprovider-oauth-token (OAuth) or provider-apideployments credential rotate, deployments connection revoke
provider-applicationprovider-oauth-client-secretdeployments oauth-app rotate, deployments oauth-app archive
mcp-servermcp-server-authdeployments mcp-server update, deployments mcp-server archive
tool-adapterextension-callback-auth or hosted-code-secretsdeployments extension update, deployments extension archive
webhook-endpointwebhook-signingSee Webhooks.
channel-bindingchannel-runtimeSee 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.

FieldMeaning
ownerType, ownerId, ownerName, ownerStatusThe resource that holds the secret.
providerKeyPresent for provider applications, connections, provider-backed tools, and channel bindings.
purposeWhat the secret is for (table above).
credentialId, generation, storeThe vault reference. store is always dynamodb-kms.
statusrevoked when the owner's lifecycle revoked the entry, otherwise active.
expiresAtThe access-token expiry of an OAuth connection.
secretNamesThe declared secret names of a hosted code tool.
createdAt, updatedAtThe 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-adapter

The 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

Reference

On this page