> For AI agents: the documentation index is at https://docs.gethandup.dev/llms.txt. Append .md to any page URL (without the trailing slash) for Markdown, for example https://docs.gethandup.dev/cli.md.

# pair_exchange

`POST /v1/pair/exchange`

Remote listener only. Trades a one-time pairing code for a device token. Rate-limited per peer IP; every attempt counts.

## Request Body required

Media type: `application/json`

`object`

- **code** (required): `string`
- **name**: `string | null`
- **cookie**: `boolean`

  Browser flow: set `HttpOnly` session cookies instead of returning the token.

## Responses

### 200

Media type: `application/json`

`object`

- **device** (required): `object`

  A paired remote device. The bearer token itself is never stored; only its
  SHA-256 digest is (see `remote::hash_token`).

  - **id** (required): `string`
  - **name** (required): `string`
  - **scope** (required): `string`

    `view` (read-only) or `decide` (adds decision, cancel and test requests).

  - **enabled** (required): `boolean`
  - **push** (required): `boolean`
  - **created_at** (required): `integer` format: int64, >= 0
  - **last_seen**: `integer | null` format: int64, >= 0

- **token**: `string | null`

  Long-lived device token (`hu_` + 64 hex). Omitted in the cookie flow.

- **host**: `string | null`

  This computer's name (its hostname), so a device paired with several
  computers can tell them apart. Absent when unknown.

### 401

Invalid, used, or expired code

### 429

Rate limited
