> ## 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.

# Phone

> Authenticate users by phone number on messaging surfaces

When your product talks to users over messages — an iMessage, SMS, or WhatsApp agent — there's no browser to run the [email OAuth redirect](/companies/authentication/email). Phone authentication flips the flow: you identify the user by their number, mint them a scoped token, and they prove the number is theirs with a one-time code before any money moves. It's the pattern Agentcard's own iMessage relay uses — and it runs entirely over MCP.

## How it goes

Connect to the MCP server with your org client credentials; everything below is a tool call.

1. **First contact — create a cardholder** for the number. Ask the user for their legal name and date of birth in conversation (cards are issued in their own name, and identity verification needs both):

```
create_cardholder({
  first_name: "Ada",
  last_name: "Lovelace",
  date_of_birth: "1990-01-15",
  phone_number: "+14155550123"
})
```

2. **Mint the user's token:**

```
mint_buy_token({ cardholder_id: "ch_…" })
```

Returns the `buyToken` plus `agentcardUserId` and `expiresAt`. The token lasts **30 days**, is scoped to that one user inside your org, and can be re-minted any time — store it keyed by the phone number and reuse it.

3. **Connect as the user with it.** The buy token is itself an MCP credential: point a session at the same server with it and you get the full [consumer toolset](/companies/mcp/overview) as that user.

```
POST https://mcp.agentcard.sh/mcp
Authorization: Bearer <buy_token>
```

Drive the conversational [buy](/companies/mcp/tools/buy) tool with the user's messages and text its replies back. Cart, confirmation, card minting, and checkout all happen inside the tool.

4. **The user proves the number.** Before their balance can be funded, the agent texts a **6-digit one-time code** and the user reads it back in the conversation. You build none of this — the agent runs the verification itself and continues once it passes.

## The code, precisely

|                |                                                |
| -------------- | ---------------------------------------------- |
| **Format**     | 6 digits, delivered by SMS (email fallback)    |
| **Expiry**     | 10 minutes, then a fresh code is needed        |
| **Attempts**   | 5 wrong tries burn the code                    |
| **Sticks for** | 60 days on the user's identity, then re-verify |

KYC and a funded balance still gate real money — the agent hands the user secure links for both when they're needed.

## Email or phone?

|                             | [Email (OAuth)](/companies/authentication/email) | Phone                               |
| --------------------------- | ------------------------------------------------ | ----------------------------------- |
| **Surface**                 | Browser — your web or desktop app                | Messaging — iMessage, SMS, WhatsApp |
| **Whose account**           | The user's own Agentcard account                 | A cardholder your org provisions    |
| **Token**                   | OAuth access + refresh tokens                    | Scoped buy token, 30 days           |
| **User proves identity by** | Typing an emailed one-time code                  | Texting back a one-time code        |