Create a vault session

curl -X POST https://api.agentcard.sh/api/v2/vault_sessions \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "object": "vault_session",
  "id": "vs_2q9d1x8f3k2m4t7w",
  "user_id": null,
  "url": "https://vault.agentcard.sh/v?vs=vs_2q9d1x8f3k2m4t7w.3k1v…",
  "channel": null,
  "destination": null,
  "expires_at": "2026-08-28T21:00:00Z",
  "poll_interval": 3,
  "test_mode": false
}

POST

api

vault_sessions

curl -X POST https://api.agentcard.sh/api/v2/vault_sessions \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "object": "vault_session",
  "id": "vs_2q9d1x8f3k2m4t7w",
  "user_id": null,
  "url": "https://vault.agentcard.sh/v?vs=vs_2q9d1x8f3k2m4t7w.3k1v…",
  "channel": null,
  "destination": null,
  "expires_at": "2026-08-28T21:00:00Z",
  "poll_interval": 3,
  "test_mode": false
}

Create the session, then deliver url to the user over the channel you already share with them. One link is one enrollment: send it to one person and bind the user_id you receive to them.

string

Omit for a new user: the session is open, the user is created at enrollment, and their id arrives in vault.session_linked (or on the session read). Pass an id you already hold and the session is connected: opening the link sends a one-time code to the contact on that account and verifying it signs the user in.

string

Connected sessions only, E.164. Used only when the account has no contact on file at all. Refused on open sessions.

number

Lifetime in seconds, 60 to 172800. Default 24 hours. Sessions are single use.

curl -X POST https://api.agentcard.sh/api/v2/vault_sessions \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "object": "vault_session",
  "id": "vs_2q9d1x8f3k2m4t7w",
  "user_id": null,
  "url": "https://vault.agentcard.sh/v?vs=vs_2q9d1x8f3k2m4t7w.3k1v…",
  "channel": null,
  "destination": null,
  "expires_at": "2026-08-28T21:00:00Z",
  "poll_interval": 3,
  "test_mode": false
}

string

Read the session by this id, never by the token inside url.

string

The link to send the user.

string | null

Null on an open session until it links.

number

Seconds to wait between reads if you poll.

Errors. 400 client_credentials_required (API key used), 400 contact_missing (connected session, nothing to send a code to), 429 rate_limited (open sessions are budgeted at 200 per organization per rolling 24 hours).

Overview

Access tokens

Connections

Vault

Purchases

Cards

Identity verification

Wallet

Wallet links

Webhook endpoints

Embed origins

Blooio connection

Create a vault session