Authenticating a user

Connecting a user is the first step of Issuing. You send them a one-time code, they read it back, and you receive a connection token that acts as them. That token is what your agent creates and uses cards with. Every call on this page is made by your server with your org token as the bearer (see step 1 of the Quickstart).

Send the user a code

By email or phone. external_user_id is optional: your own id for the user, returned on webhooks so you can match them up.

curl -X POST https://api.agentcard.sh/api/v2/connect/start \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "external_user_id": "your-internal-id"}'

{ "object": "connect_attempt", "connect_id": "ca_9k1m4x7d", "channel": "email" }

Verify the code

In sandbox the code is always 111111.

curl -X POST https://api.agentcard.sh/api/v2/connect/verify \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connect_id": "ca_9k1m4x7d", "code": "111111"}'

{
  "object": "connection",
  "access_token": "act_1a2b3c…",
  "refresh_token": "rct_4d5e6f…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": { "id": "user_7g8h9i", "email": "user@example.com", "phone": null }
}

Store all three. user.id is how your server names the user on /api/v2 calls. access_token is the connection token your agent uses. The connection.created webhook fires here. Once per user, before any card or balance action:

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

A user_info_required error later means this step was skipped.

Refresh the connection

Connection tokens expire after one hour. Rotate them with the refresh token, using your org token as the bearer:

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

Each refresh returns a new pair and invalidates the old one. Store what comes back. An invalid_refresh_token means it was already used or expired: reconnect the user.

Users you know by phone only

If your agent lives in iMessage or WhatsApp, you may not want to relay a code. Create an onboarding attempt instead: it returns a wallet link to text, the code fires inside our page at the user’s first money action, and you exchange the attempt for the connection afterwards. See Connections in the API reference.

Sandbox

Sandbox sends email but not SMS, and the code is always 111111. Sandbox users are isolated: connecting anyone@example.com in sandbox can never touch a real account.

Getting started

Vault

Issuing

Authenticating a user

Send the user a code

Verify the code

Refresh the connection

Users you know by phone only

Sandbox

​Send the user a code

​Verify the code

​Record consent

​Refresh the connection

​Users you know by phone only

​Sandbox

Send the user a code

Verify the code

Record consent

Refresh the connection

Users you know by phone only

Sandbox