Connect users

Before a user can have a wallet in your product, two things happen: your server proves who it is, and the user proves who they are. Both take one call each. This page is the server side of the whole integration.

Keys and tokens

There are only three credentials in the system, and each one has exactly one place it goes.

Credential	What it is	Who holds it	Where it goes
Org credential	Your `client_id` and `client_secret`, exchanged for a bearer token	Your server only. Never a browser, never an agent	Every `/api/v2` call your server makes
Wallet link	A short-lived URL that opens one user’s wallet	Travels to the user: through your frontend, a text, or a chat	The wallet component, on any platform
Connection token	One user’s session, with a refresh token	Your server stores and refreshes it	Calls made on behalf of that user

The pattern to remember: your org credential stays on your server. The wallet link is the only thing that travels to the user. The connection token comes back when a user verifies, and your server keeps it.

Authenticate your server

Exchange your credentials for a bearer token. The request is form-encoded, per OAuth:

curl -X POST https://api.agentcard.sh/api/v2/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

const res = await fetch("https://api.agentcard.sh/api/v2/oauth/token", {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
  }),
});
const { access_token } = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)
access_token = res.json()["access_token"]

You get back an access_token with an expires_in. Cache it and refresh when it expires. Whether it’s a sandbox or production token follows the credential, not the URL.

Connect a user

Send the user a one-time code, on email or phone:

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"}'

const res = await fetch("https://api.agentcard.sh/api/v2/connect/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com", external_user_id: "your-internal-id" }),
});
const attempt = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/connect/start",
    headers={"Authorization": f"Bearer {ORG_TOKEN}"},
    json={"email": "user@example.com", "external_user_id": "your-internal-id"},
)
attempt = res.json()

external_user_id is optional. It’s your own id for the user, and it comes back on webhooks so you can match them up. Verify the code the user gives you. 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": "CONNECT_ATTEMPT_ID", "code": "111111"}'

const res = await fetch("https://api.agentcard.sh/api/v2/connect/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ connect_id: "CONNECT_ATTEMPT_ID", code: "111111" }),
});
const connection = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/connect/verify",
    headers={"Authorization": f"Bearer {ORG_TOKEN}"},
    json={"connect_id": "CONNECT_ATTEMPT_ID", "code": "111111"},
)
connection = res.json()

The response is the connection: the user’s user_id, an access_token (the connection token), and a refresh_token. Store all three. The connection.created webhook fires here. Then record the user’s authorization once:

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_ID"}'

const res = await fetch("https://api.agentcard.sh/api/v2/connect/consent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ user_id: "USER_ID" }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/connect/consent",
    headers={"Authorization": f"Bearer {ORG_TOKEN}"},
    json={"user_id": "USER_ID"},
)
data = res.json()

Consent is what makes the user’s wallet available to your product. Wallet links won’t be created without it.

Create wallet links

With a connected, consented user, your server can create wallet links whenever the wallet should open:

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

const res = await fetch("https://api.agentcard.sh/api/v2/wallet_links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ user_id: "USER_ID" }),
});
const link = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/wallet_links",
    headers={"Authorization": f"Bearer {ORG_TOKEN}"},
    json={"user_id": "USER_ID"},
)
link = res.json()

The response has a url. That link opens the user’s wallet on any platform: the web embed, the iOS sheet, a text message, or the hosted page. Links are short-lived; create a fresh one each time rather than storing them.

Keep the session alive

Connection tokens expire. Rotate them with the refresh token:

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

const res = await fetch("https://api.agentcard.sh/api/v2/connect/refresh", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ORG_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ refresh_token: "REFRESH_TOKEN" }),
});
const session = await res.json();

import requests

res = requests.post(
    "https://api.agentcard.sh/api/v2/connect/refresh",
    headers={"Authorization": f"Bearer {ORG_TOKEN}"},
    json={"refresh_token": "REFRESH_TOKEN"},
)
session = res.json()

Each refresh returns a new pair and invalidates the old one, so store what comes back.

Webhooks you will receive

connection.created when a user verifies, with your external_user_id on it

When it fails

An auth error usually means the wrong credential for the call. Check the table at the top.
user_info_required on wallet links means consent was never recorded for that user. Call /connect/consent.
subscription_required in production means your organization hasn’t subscribed yet. Sandbox never requires one.
invalid_refresh_token means the refresh token was already used or expired. Reconnect the user.

Sandbox behavior

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

Get started

The wallet

Platforms

Purchase

Tools

Ship

Keys and tokens

Authenticate your server

Connect a user

Create wallet links

Keep the session alive

Webhooks you will receive

When it fails

Sandbox behavior

​Keys and tokens

​Authenticate your server

​Connect a user

​Create wallet links

​Keep the session alive

​Webhooks you will receive

​When it fails

​Sandbox behavior

Keys and tokens

Authenticate your server

Connect a user

Create wallet links

Keep the session alive

Webhooks you will receive

When it fails

Sandbox behavior