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

## The connection object

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

| 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": "usr_7g8h9i", "email": "user@example.com", "phone": null }
}
```

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

Webhook: `connection.created`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.