Vaults and credentials

Vaults group credentials within your organization. All endpoints require an x-api-key header. Secret values are accepted on create or rotation but are never returned.

Create a vault

POST /v1/vaults

curl -X POST "https://api.herm.run/v1/vaults" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "displayName": "Acme production connectors",
    "metadata": { "customerId": "customer_123" }
  }'

The response is a vault object:

{
  "id": "vault_123",
  "type": "vault",
  "displayName": "Acme production connectors",
  "metadata": { "customerId": "customer_123" },
  "archivedAt": null,
  "createdAt": "2026-07-23T18:00:00.000Z",
  "updatedAt": "2026-07-23T18:00:00.000Z"
}

Manage vaults

Method	Endpoint	Behavior
`GET`	`/v1/vaults`	List active vaults, newest first.
`GET`	`/v1/vaults/{vaultId}`	Get an active or archived vault.
`POST`	`/v1/vaults/{vaultId}/archive`	Archive a vault. Idempotent.
`DELETE`	`/v1/vaults/{vaultId}`	Permanently delete an empty vault and its agent attachments.

Deleting a vault is permanent. Delete every credential first so its stored value is removed, then delete the empty vault. A non-empty vault returns 409 conflict. Archiving keeps a vault available for inspection but prevents new credentials or agent attachments.

Create a static bearer credential

POST /v1/vaults/{vaultId}/credentials

curl -X POST "https://api.herm.run/v1/vaults/vault_123/credentials" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "displayName": "Linear MCP",
    "auth": {
      "type": "static_bearer",
      "mcpServerUrl": "https://mcp.example.com/linear",
      "token": "secret-token"
    }
  }'

The response redacts token:

{
  "id": "credential_123",
  "type": "vault_credential",
  "vaultId": "vault_123",
  "displayName": "Linear MCP",
  "metadata": null,
  "auth": {
    "type": "static_bearer",
    "mcpServerUrl": "https://mcp.example.com/linear"
  },
  "archivedAt": null,
  "createdAt": "2026-07-23T18:01:00.000Z",
  "updatedAt": "2026-07-23T18:01:00.000Z"
}

Create an MCP OAuth credential

Use mcp_oauth when you already have access and refresh tokens from an OAuth flow:

{
  "displayName": "Customer OAuth connection",
  "auth": {
    "type": "mcp_oauth",
    "mcpServerUrl": "https://mcp.example.com/service",
    "accessToken": "access-token",
    "expiresAt": "2026-07-23T19:00:00.000Z",
    "refresh": {
      "tokenEndpoint": "https://auth.example.com/oauth/token",
      "clientId": "client-id",
      "refreshToken": "refresh-token",
      "tokenEndpointAuth": {
        "type": "client_secret_basic",
        "clientSecret": "client-secret"
      }
    }
  }
}

tokenEndpointAuth.type can be none, client_secret_basic, or client_secret_post. Responses redact access tokens, refresh tokens, and client secrets.

Manage credentials

Method	Endpoint	Behavior
`GET`	`/v1/vaults/{vaultId}/credentials`	List active credentials.
`GET`	`/v1/vaults/{vaultId}/credentials/{credentialId}`	Get an active or archived credential with redacted auth.
`PATCH`	`/v1/vaults/{vaultId}/credentials/{credentialId}`	Update display metadata or rotate secret values.
`POST`	`/v1/vaults/{vaultId}/credentials/{credentialId}/archive`	Archive a credential. Idempotent.
`DELETE`	`/v1/vaults/{vaultId}/credentials/{credentialId}`	Permanently delete a credential.

Rotate a static bearer token without changing its MCP server URL:

curl -X PATCH "https://api.herm.run/v1/vaults/vault_123/credentials/credential_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "token": "replacement-token"
    }
  }'

Credential auth type is immutable. For MCP OAuth credentials, PATCH can replace accessToken, expiresAt, and refresh.refreshToken.

Attach vaults to an agent

GET /v1/agents/{agentId}/vaults
PUT /v1/agents/{agentId}/vaults

GET returns the attached vaults, the agent’s updatedAt, and connection status for the latest version’s MCP servers. Use that timestamp for optimistic concurrency when replacing the attachment set:

curl -X PUT "https://api.herm.run/v1/agents/agent_123/vaults" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "vaultIds": ["vault_123"],
    "expectedUpdatedAt": "2026-07-23T18:02:00.000Z"
  }'

PUT replaces the complete attachment set. Send an empty vaultIds array to detach all vaults. A stale expectedUpdatedAt returns 409 conflict; reload the agent vault state before retrying. MCP server status is one of:

Status	Meaning
`public`	No attached credential matches the server URL.
`connected`	Exactly one usable credential matches.
`reconnect`	The matching OAuth credential is expired or invalid.
`conflict`	Multiple attached credentials match the same server URL.
`unavailable`	A matching credential is temporarily unavailable.

Errors

Status	Error	When
`400`	`validation_error`	The request is malformed or a field is invalid.
`404`	`not_found`	The vault, credential, or agent is not in your organization.
`409`	`conflict`	Agent vault access changed before an attachment update completed.
`502`	`server_error`	The credential operation could not be completed.

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Vaults and credentials

Create a vault

Manage vaults

Create a static bearer credential

Create an MCP OAuth credential

Manage credentials

Attach vaults to an agent

Errors

​Create a vault

​Manage vaults

​Create a static bearer credential

​Create an MCP OAuth credential

​Manage credentials

​Attach vaults to an agent

​Errors

Create a vault

Manage vaults

Create a static bearer credential

Create an MCP OAuth credential

Manage credentials

Attach vaults to an agent

Errors