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": "usr_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": "usr_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

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

Guides

Vault

Issuing

Partners

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