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

# Connections

> Connect a user to your platform: send a code, verify it, and get a token that acts as them.

A **connection** links one of your users to your platform. You send a one-time code to their email or phone, they read it back, and you receive a token pair: the `access_token` acts **as that user** (it is the bearer on `/buy` and the member-token card endpoints) and the `refresh_token` keeps it alive. Completing the code is the authorization. There is no separate approval screen.

Connection access tokens expire after one hour. Each refresh returns a new refresh token and invalidates the old one.

**Attested onboarding** is the variant for users you already know by phone number: you create an onboarding attempt, text the returned wallet link, and the code fires once inside our page at their first money action. You collect the connection afterwards.

## The connection object

Returned by [Verify the code](/api-reference/connections/verify), [Refresh the connection](/api-reference/connections/refresh), and the onboarding-attempt exchange.

| Field           | Type           | Description                                                                                                                                                    |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`        | string         | `connection`                                                                                                                                                   |
| `access_token`  | string         | The user's connection token. Acts as this user. Bearer on `/buy` and the member-token card endpoints. Never the `Authorization` header of a platform endpoint. |
| `refresh_token` | string         | Exchange it on `/connect/refresh` before `access_token` expires. Each refresh returns a new one and invalidates the old.                                       |
| `token_type`    | string         | `Bearer`                                                                                                                                                       |
| `expires_in`    | integer        | Seconds until `access_token` expires (3600).                                                                                                                   |
| `user.id`       | string         | Store it. Every platform endpoint names the user by this id.                                                                                                   |
| `user.email`    | string or null | Set when the user connected by email.                                                                                                                          |
| `user.phone`    | string or null | Set when the user connected by phone.                                                                                                                          |

```json theme={null}
{
  "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 }
}
```

## The onboarding attempt object

| Field        | Type    | Description                                                             |
| ------------ | ------- | ----------------------------------------------------------------------- |
| `id`         | string  | `oa_…`                                                                  |
| `wallet_url` | string  | The link to text the user. Returned on create.                          |
| `verified`   | boolean | Whether the person has completed the one-time code inside our page.     |
| `exchanged`  | boolean | Whether the connection was already collected. The exchange is one-time. |
| `expires_at` | string  | When the attempt stops being exchangeable.                              |

## Endpoints

| Endpoint                                         |                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `POST /api/v2/connect/start`                     | [Send a code](/api-reference/connections/start)                                       |
| `POST /api/v2/connect/verify`                    | [Verify the code](/api-reference/connections/verify): returns the token pair          |
| `POST /api/v2/connect/consent`                   | [Record consent](/api-reference/connections/consent)                                  |
| `POST /api/v2/connect/refresh`                   | [Refresh the connection](/api-reference/connections/refresh)                          |
| `POST /api/v2/onboarding_attempts`               | [Start attested onboarding](/api-reference/connections/onboarding-attempt-create)     |
| `GET /api/v2/onboarding_attempts/{id}`           | [Get an onboarding attempt](/api-reference/connections/onboarding-attempt-get)        |
| `POST /api/v2/onboarding_attempts/{id}/exchange` | [Exchange for the connection](/api-reference/connections/onboarding-attempt-exchange) |

Webhook: `connection.created`.