Skip to main content
POST
Propose vault policy update
Creates a pending policy update. External-signer Vaults return an EIP-712 signing action; managed Vaults send an email approval challenge to the verified managed contact. Complete it with Authorize a Vault policy. Idempotency-Key is required.

Authorizations

Authorization
string
header
required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Idempotency-Key
string
required

Use this for retry-safe payment operations from your backend.

Example:

"payment-request-001"

Stableyard-Version
enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options:
2026-09-09

Path Parameters

accountId
string
required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json
policy
object
required
reason
string
Maximum string length: 280

Response

Pending policy

id
string
required
Example:

"vault_policy_123"

vaultId
string
required
Example:

"vault_123"

version
integer
required
Required range: x >= 1
policySchemaVersion
integer
required
Required range: x >= 1
status
enum<string>
required
Available options:
draft,
pending_authorization,
authorized,
installing,
active,
superseded,
revoked,
failed
ownershipMode
enum<string>
required
Available options:
external,
stableyard
allowedTokens
object[]
required
spendLimits
object
required
yieldRules
object
required
resourceVersion
integer
required
Required range: x >= 1
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
authorization
object

Present on single-policy responses while authorization is pending.

nextAction
Vault action required · object | null
reason
string | null
failureCode
string | null