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. 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
credentialType
enum<string>
required

How this credential is used.

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

Operator-facing label.

Maximum string length: 256
integrationConnectionId
string

Connected account this grant uses.

integrationPermission
string

Provider permission preset applied when minting.

integrationResources
string[]

Resources within the connection this grant may reach.

mcpServerUrl
string

MCP server this credential unlocks. Immutable after creation.

metadata
object

Caller-owned labels. For imap_oauth, metadata.imap_oauth is the required validated OAuth registration, fixed after creation.

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 secretValue. Fixed at create.

Available options:
anthropic,
github_packages_npm,
openai,
slack,
stripe
secretName
string

Environment variable or header name the secret binds to.

secretRef
string

Reference to material stored outside this service.

secretValue
string
write-only

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

Response

Created

createdAt
string<date-time>
required
read-only

Server-assigned RFC 3339 creation time.

credentialId
string
required
read-only

Server-assigned credential identifier (UUID), unique within the vault.

credentialType
string
required

How the credential is used. Legacy rows may report additional kinds.

organizationId
string
required
read-only

Organization that owns this record, resolved from the authenticated principal.

updatedAt
string<date-time>
required
read-only

Server-assigned RFC 3339 last update time.

vaultId
string
required
read-only

Vault that owns this credential (UUID).

allowedHosts
string[]

IMAP credentials only: exactly one immutable lowercase mail-server hostname, without a wildcard, scheme, port, or path. Required on create and enforced before authentication.

Required array length: 1 element
Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$
displayName
string

Optional operator-facing credential label.

integrationConnectionId
string

Organization integration connection granted by this credential (UUID).

integrationPermission
string

Validated provider permission preset.

integrationResources
string[]

Provider resources the integration grant is narrowed to.

mcpServerUrl
string

MCP server this credential may be sent to.

metadata
object

Caller-supplied labels, with compatibility-only scope data excluded.

platformMcpService
enum<string>
read-only

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

Available options:
slack_tools
provider
enum<string>

Catalog service for a proxied env_var credential, absent for credentials supplied directly to the sandbox.

Available options:
anthropic,
github_packages_npm,
openai,
slack,
stripe
secretName
string

Environment variable or header name the secret binds to.

secretRef
string

Opaque pointer to externally stored secret material.