API reference - Agentcard

Base URL: https://api.agentcard.sh There is no separate sandbox host. Whether a call runs in sandbox or production is decided by the credential you use, never by the URL.

Resources

Access tokens

Exchange client credentials for the platform token every call needs.

Connections

Connect a user to your platform and get a token that acts as them.

Vault

Store a user’s own card and authorize checkouts with it.

Purchases

One conversational endpoint that places real orders.

Cards

One-time virtual cards created against a member’s added card.

Identity verification

KYC: documents, extra fields, face scan, status.

Webhook endpoints

Blooio connection

Let Agentcard send Vault links from your Blooio numbers.

Authentication

Every endpoint is called from your backend with a platform access token:

Authorization: Bearer <access_token>

Mint it on Create an access token from your client_id and client_secret (dashboard → Organization → Developer → Credentials). A sandbox client mints sandbox tokens, a production client mints production tokens. Tokens live one hour.

Two tokens, two jobs

Token	Where you get it	What it does
Platform access token	Create an access token	Authenticates your platform. The bearer on almost every endpoint here.
Connection token	Verify the code	Acts as one user. The bearer on `/buy` and on the member-token card endpoints.

The connection token belongs to the user. Platform endpoints name the user with user_id instead of taking their token. Keep it fresh with Refresh the connection.

Test from this reference

Open Create an access token, paste a sandbox client_id and client_secret, hit Send.
Paste the access_token into the Authorization field on any endpoint page. It is remembered as you move between pages.
Fill the parameters and hit Send. You are hitting the live API. In sandbox the connect code is always 111111.

Ids

Every id Agentcard issues starts with a prefix that names the object it points to, then an underscore and a random part, such as card_3f9a1c2e4b5d6a7f8e9d0c1b. The prefix tells you what an id holds when you read a log, a response, or a webhook.

Prefix	Object
`org_`	An organization
`usr_`	A user
`ch_`	A cardholder
`card_`	A card Agentcard issued
`cc_`	An added card
`vc_`	A stored card in the Vault
`ca_`	A connect attempt
`cns_`	A consent
`oa_`	An onboarding attempt
`cos_`	A cardholder onboarding session
`vs_`	A vault session
`cprep_`	A checkout preparation
`cauth_`	A checkout authorization
`cout_`	A reported checkout outcome
`apg_`	An autopilot grant
`ape_`	An autopilot execution
`pol_`	A preset
`appr_`	An approval
`conv_`	A purchase conversation
`txn_`	A card transaction
`owt_`	A company wallet transfer
`rcv_`	A recovery
`wd_`	A withdrawal
`wrec_`	A withdrawal recipient
`we_`	A webhook endpoint
`whd_`	A webhook delivery
`evt_`	An event
`rdm_`	A rewards redemption
`pl_`	A pending merchant link

An id you received earlier may carry no prefix, such as cmturxopj0004cbpswhqdeyju on a stored card. Treat every id as an opaque string: store it and pass it back exactly as you received it, never parse it, and never check it for a prefix. Three values are not Agentcard object ids and keep their own shape: client_id is your OAuth client identifier, external_user_id is the id you gave Agentcard for a user, and the id on a transaction.* event is the card network’s reference for that charge.

Errors

Every error uses the same envelope:

{
  "error": {
    "code": "invalid_code",
    "message": "That code is invalid or expired.",
    "docs": "https://docs.agentcard.sh/api-reference/overview"
  }
}

code is stable and machine-readable. Branch on it. message is safe to log. Each endpoint page lists the codes it can return.

Webhooks

Events are signed and delivered to the endpoints you register under Webhook endpoints. Every event and its payload is documented in the Webhooks tab.

​Resources