Skip to main content
POST
Register a credential reference in a vault

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string

Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

vaultId
string<uuid>
required

Vault id (UUID) as returned by managedAgentsCreateVault or managedAgentsListVaults.

Body

application/json

Request body for adding one credential to a standalone Managed Agents vault. Secret material is encrypted at rest and never returned.

credential_type
enum<string>
required

How this credential is used.

Available options:
bearer_token,
env_var,
webhook_secret,
integration
display_name
string

Operator-facing label.

Maximum string length: 256
integration_connection_id
string

Connected account this grant uses.

integration_permission
string

Provider permission preset applied when minting.

integration_resources
string[]

Resources within the connection this grant may reach.

mcp_server_url
string

MCP server this credential unlocks. Immutable after creation.

metadata
object

Free-form caller-owned labels stored and returned verbatim.

provider
enum<string>

env_var only. A service from the platform catalog: the agent calls the service with this credential but never sees the value. Omitted, the value is in the sandbox environment, readable by the agent. Any other value is refused. Requires secret_value. Fixed at create.

Available options:
anthropic,
openai,
slack,
stripe
secret_name
string

Environment variable or header name the secret binds to.

secret_ref
string

Reference to material stored outside this service.

secret_value
string

Credential material. Encrypted at rest and never returned or logged.

Response

OK

created_at
string<date-time>
required

RFC 3339 timestamp of when this record was created. Server-assigned.

credential_id
string
required

Identifier for this credential (UUID). Server-assigned, and unique only within its vault.

credential_type
string
required

How the credential is used. Legacy rows may report additional kinds, so this remains a string rather than a closed response enum.

organization_id
string
required

Organization that owns this record. Resolved from the authenticated principal; never accepted from the caller.

updated_at
string<date-time>
required

RFC 3339 timestamp of the last change to this record. Server-assigned.

vault_id
string
required

Vault this credential belongs to (UUID).

display_name
string

Operator-facing label for the credential.

integration_connection_id
string

Organization integration connection this credential grants a session (UUID).

integration_permission
string

Permission preset applied when a token is minted for this grant.

integration_resources
string[]

Resources within the connection the grant is narrowed to.

mcp_server_url
string

MCP server this credential may be sent to.

metadata
object

Free-form caller-supplied labels, excluding compatibility metadata reserved by another contract.

platform_mcp_service
enum<string>

Deployment-derived identity of an exact platform MCP service this credential targets; never caller-controlled or stored.

Available options:
slack_tools
provider
enum<string>

The catalog service an env_var credential is used with; the agent never sees its value. Absent when the value is in the sandbox environment.

Available options:
anthropic,
openai,
slack,
stripe
secret_name
string

Environment variable or header name the secret binds to inside the sandbox.

secret_ref
string

Pointer to material stored in an external secret manager. Opaque to this service.