> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every v2 endpoint, grouped by the resource it acts on. Each page has parameters, responses, and a live playground.

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

<CardGroup cols={2}>
  <Card title="Access tokens" href="/api-reference/access-tokens/overview">Exchange client credentials for the platform token every call needs.</Card>
  <Card title="Connections" href="/api-reference/connections/overview">Connect a user to your platform and get a token that acts as them.</Card>
  <Card title="Vault" href="/api-reference/vault/overview">Store a user's own card and authorize checkouts with it.</Card>
  <Card title="Purchases" href="/api-reference/purchases/overview">One conversational endpoint that places real orders.</Card>
  <Card title="Cards" href="/api-reference/cards/overview">One-time virtual cards created against a member's added card.</Card>
  <Card title="Identity verification" href="/api-reference/identity-verification/overview">KYC: documents, extra fields, face scan, status.</Card>
  <Card title="Webhook endpoints" href="/api-reference/webhook-endpoints/overview">Register where events are delivered and rotate signing secrets.</Card>
  <Card title="Blooio connection" href="/api-reference/blooio/overview">Let Agentcard send Vault links from your Blooio numbers.</Card>
</CardGroup>

## Authentication

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

```
Authorization: Bearer <access_token>
```

Mint it on [Create an access token](/api-reference/access-tokens/create) 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](/api-reference/access-tokens/create) | Authenticates **your platform**. The bearer on almost every endpoint here. |
| **Connection token** | [Verify the code](/api-reference/connections/verify) | 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](/api-reference/connections/refresh).

## Test from this reference

1. Open [Create an access token](/api-reference/access-tokens/create), paste a sandbox `client_id` and `client_secret`, hit **Send**.
2. Paste the `access_token` into the **Authorization** field on any endpoint page. It is remembered as you move between pages.
3. 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:

```json theme={null}
{
  "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](/api-reference/webhook-endpoints/overview). Every event and its payload is documented in the [Webhooks](/webhooks/overview) tab.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.