Register a credential reference in a vault
Registers one credential in a vault and returns the stored reference. Supply exactly one of secret_value (encrypted under the organization’s key and stored as ciphertext) or secret_ref (material you already stored yourself) for secret-backed kinds. Integration grants carry neither; they reference a connected account that mints short-lived credentials. Secret material is never echoed back on this or any later response. An optional Idempotency-Key makes a retry after an ambiguous transport failure replay the first response instead of registering a second credential.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
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.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization 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.
1Path Parameters
Vault id (UUID) as returned by managedAgentsCreateVault or managedAgentsListVaults.
Body
Request body for adding one credential to a standalone Managed Agents vault. Secret material is encrypted at rest and never returned.
How this credential is used.
bearer_token, env_var, webhook_secret, integration Operator-facing label.
256Connected account this grant uses.
Provider permission preset applied when minting.
Resources within the connection this grant may reach.
MCP server this credential unlocks. Immutable after creation.
Free-form caller-owned labels stored and returned verbatim.
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.
anthropic, openai, slack, stripe Environment variable or header name the secret binds to.
Reference to material stored outside this service.
Credential material. Encrypted at rest and never returned or logged.
Response
OK
RFC 3339 timestamp of when this record was created. Server-assigned.
Identifier for this credential (UUID). Server-assigned, and unique only within its vault.
How the credential is used. Legacy rows may report additional kinds, so this remains a string rather than a closed response enum.
Organization that owns this record. Resolved from the authenticated principal; never accepted from the caller.
RFC 3339 timestamp of the last change to this record. Server-assigned.
Vault this credential belongs to (UUID).
Operator-facing label for the credential.
Organization integration connection this credential grants a session (UUID).
Permission preset applied when a token is minted for this grant.
Resources within the connection the grant is narrowed to.
MCP server this credential may be sent to.
Free-form caller-supplied labels, excluding compatibility metadata reserved by another contract.
Deployment-derived identity of an exact platform MCP service this credential targets; never caller-controlled or stored.
slack_tools 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.
anthropic, openai, slack, stripe Environment variable or header name the secret binds to inside the sandbox.
Pointer to material stored in an external secret manager. Opaque to this service.