# Part 2F — Agent Phone (devices and their own API)

Ringmaster Agent Phone is the desktop app agents keep running to pick up calls ([AGENT-PHONE.md](../AGENT-PHONE.md)).
This part has two sides:

- **K. For the client app (API key):** connect an agent's Agent Phone with a one-time code, list their devices, remove
  one. This is the "Connect Agent Phone" button on your dashboard.
- **L. Agent Phone's own API (device token):** what the app itself calls. You only need it to build your own app;
  Ringmaster's Agent Phone already does all of it.

Who does what:

| Job | Who |
|---|---|
| Who the person is (password, 2FA, staff accounts) | **Your app.** Ask for a pairing code only after your own login |
| May this computer take this agent's calls (keys, tokens, revoke) | **Ringmaster.** The engine checks every accept, decline and hang-up |

```
Agent signed in to your dashboard → "Connect Agent Phone"
  your backend ── POST /v1/accounts/{acc}/agents/{ref}/devices/pairings ──► engine
              ◄── { code: "482913", link: "ringmaster-agent://pair?code=482913&host=…", expiresAt } ──
  show the code (and the link) → the agent types the code into Agent Phone
Agent Phone: makes a P-256 key (kept in the OS password vault)
  POST /v1/agent/pair { code, deviceName, platform } + DPoP proof (signed with that key)
  ◄── { deviceId, accessToken (15 min), refreshToken }
```

---

# K. Devices (client app, API key)

## K1. A pairing code
**Purpose**: A one-time code for one agent. It works **once**, for **5 minutes**. Pairing tries are limited per IP.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/accounts/{accountId}/agents/{ref}/devices/pairings`

**Success Response JSON Sample** (`201`):
```json
{
  "success": true,
  "httpStatus": "201 CREATED",
  "message": "Pairing code",
  "action": null,
  "action_time": "2026-11-14T14:20:02.118",
  "data": {
    "code": "078183",
    "link": "ringmaster-agent://pair?code=078183&host=https%3A%2F%2Fapi.ringmaster.example",
    "expiresAt": "2026-11-14T11:25:02.101Z"
  }
}
```
Show both: the **code** to type, and the **link** as a button (it opens Agent Phone where links are set up).

**Errors**: `404` "Agent not found: …".

## K2. List an agent's devices
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/accounts/{accountId}/agents/{ref}/devices`

```json
"data": [
  { "id": "1400d27e-8e21-4f9c-be7d-8e7c77c5f660", "name": "Agent Phone on reception-pc", "platform": "linux",
    "appVersion": "0.1.0", "pairedAt": "2026-11-14T11:24:05Z", "lastSeenAt": "2026-11-14T11:24:13Z", "lastIp": "192.168.100.215" }
]
```
At most **5** devices per agent; pairing a sixth answers `409 TOO_MANY_DEVICES`.

## K3. Remove a device
**Endpoint**: <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/accounts/{accountId}/agents/{ref}/devices/{deviceId}`

**Success Response**: `200`, `message` "Device removed". The device is cut off **at once**: its tokens stop working, it
is taken out of the lobby, it receives `device_revoked` and goes back to its pairing screen. You get
[`agent.device_revoked`](3-webhooks.md#agentdevice_paired--agentdevice_revoked).

A device is also revoked when: the agent is removed, its old refresh token is used again (copied: reason
`TOKEN_REUSED`), it was not used for 30 days (`UNUSED`), or the agent signs out on it (`SIGNED_OUT`).

## K4. Shared computers (stations)
A **station** is a computer the business shares (the reception PC). It belongs to no agent and rings for nobody until
an agent starts a shift on it **from your dashboard**, after signing in to your app: your login is the proof of who they
are. The computer switches by itself (it waits in its own room, `station-{id}`). One agent at a time; starting a shift
while someone else is on replaces them (never during a call: `409 SHIFT_BUSY`).

| Method | Path | Does |
|---|---|---|
| POST | `/accounts/{accountId}/stations/pairings` | A one-time code for a new shared computer (same shape as [K1](#k1-a-pairing-code)) |
| GET | `/accounts/{accountId}/stations` | Stations and who is on shift: `id`, `name`, `platform`, `onShiftRef`, `onShiftName`, `shiftSince`, `idleEndMin`, `endAtTime`, `lastSeenAt` |
| PATCH | `/accounts/{accountId}/stations/{stationId}` | `{"idleEndMin": 120, "endAtTime": "17:30"}`: end the shift after that many minutes without calls (0 = never), and at that time of day (`""` = never) |
| POST | `/accounts/{accountId}/stations/{stationId}/shift` | `{"agentRef": "asha"}`: start the shift ("Start my shift on Reception PC") |
| DELETE | `/accounts/{accountId}/stations/{stationId}/shift` | End the shift now |
| DELETE | `/accounts/{accountId}/stations/{stationId}` | Remove the station (signed out at once) |
| PUT | `/accounts/{accountId}/agents/{ref}/pin` | Optional: `{"pin": "4321"}`, 4–6 digits, stored hashed (`""` removes it) |

**PINs are optional** and Ringmaster's Agent Phone doesn't ask for them: a shift starts from the dashboard. They exist
for a client app that builds its own station screen ([L7](#l7-shifts-stations-only)); five wrong PINs lock the agent
out for 15 minutes (`409 PIN_LOCKED`). Webhooks: `station.paired`,
`station.removed`, [`agent.shift_started` · `agent.shift_ended`](3-webhooks.md#agentshift_started--agentshift_ended).

---

# L. Agent Phone's API (device token)

Base: `{base_url}/agent`. Every call except L1 and L2 sends `Authorization: Bearer <accessToken>`. A device token
works **only** here (never on `/v1/accounts/…`), and only for its own agent: there is no `agentRef` in these requests.

`401 DEVICE_UNAUTHORIZED` means the token expired, or the device was removed: refresh once; if that fails too, go back
to the pairing screen.

## DPoP proofs
L1 and L2 carry a header `DPoP: <proof>` (RFC 9449): a compact JWS signed with the device's key.

| Part | Content |
|---|---|
| header | `{"typ": "dpop+jwt", "alg": "ES256", "jwk": {"kty": "EC", "crv": "P-256", "x": "…", "y": "…"}}` |
| claims | `{"htm": "POST", "htu": "<full URL of this request>", "iat": <unix seconds>, "jti": "<random, ≥ 12 chars>"}` |
| signature | ES256 over `base64url(header).base64url(claims)`, as raw R‖S (64 bytes), base64url |

Proofs older than 60 s, or seen before (same `jti`), are refused. On refresh the key must be the one used at pairing.

## L1. Pair
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/agent/pair` (no token; DPoP proof)

**Request**:
```json
{ "code": "078183", "deviceName": "Agent Phone on reception-pc", "platform": "linux", "appVersion": "0.1.0" }
```

**Success Response** (`201`):
```json
"data": { "deviceId": "1400d27e-8e21-4f9c-be7d-8e7c77c5f660", "accessToken": "rma_…", "expiresIn": 900,
          "refreshToken": "rmr_…", "agentRef": "asha", "agentName": "Asha", "business": "Ringmaster Lab" }
```
Keep the private key and the refresh token in the OS password vault; keep the access token in memory only.

**Errors**: `401` "This code is wrong or has expired…" · `401` DPoP errors · `409 TOO_MANY_DEVICES` · `429` too many tries.

## L2. Refresh
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/agent/token` (no token; DPoP proof from the same key)

**Request**: `{"refreshToken": "rmr_…"}`. **Success Response**: the same shape as L1, with a **new** refresh token.
Save it before anything else: the old one is dead, and using it again revokes the device.

## L3. The desk (everything the app shows)
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/agent/me`

Same answer as [I14](2d-agents.md#i14-the-agents-desk) for this device's agent.

## L4. Search the dial pad
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/agent/search?digits=0745`

Same as [I15](2d-agents.md#i15-search-for-the-dial-pad): digits match numbers; letters match the client app's
contacts and earlier callers' names.

## L5. Lobby token
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/agent/lobby-token`

Like [I12](2d-agents.md#i12-lobby-token), with the identity `agent-{agentId}:dev-{deviceId}`.

## L6. Calls
| Method | Path | Does | Same as |
|---|---|---|---|
| POST | `/agent/calls/{callId}/accept` | Accept the ringing call; returns the call room token | [J1](2d-agents.md#j1-accept-a-ringing-call) |
| POST | `/agent/calls/{callId}/decline` | Body `{"reason": "WITH_CUSTOMER"}` (optional) | [J2](2d-agents.md#j2-decline-a-ringing-call) |
| POST | `/agent/calls/{callId}/take` | Answer a waiting caller now, even while away | [J9](2d-agents.md#j9-take-a-waiting-caller) |
| POST | `/agent/available` | "I'm back": `AVAILABLE` again (out of wrap-up: ready). Going away stays on the dashboard | [I10](2d-agents.md#i10-set-an-agents-status) |
| POST | `/agent/calls/{callId}/hangup` | Hang up (cancels the dial if the other phone still rings) | [J6](2d-agents.md#j6-hang-up) |
| POST | `/agent/calls/{callId}/join` | Join an outgoing call that is this agent's (after `outgoing`) | [J7](2d-agents.md#j7-join-an-outgoing-call) |
| POST | `/agent/calls/{callId}/call-back` | Call the other person of an earlier call back, from the same line | [J8](2d-agents.md#j8-call-someone-back) |
| POST | `/agent/calls` | Dial pad: `{"numberId": "…", "to": "0745051250"}` | [Click-to-call](2c-calls.md) with `meta.via: "dial-pad"` |

Pairing with a **station** code (K4) gives `"kind": "STATION"` and `agentRef: null` in L1's answer.

## L7. Shifts (stations only)
A station's token acts for the agent on shift; with nobody on shift, agent endpoints answer `409 NO_SHIFT`.

| Method | Path | Does |
|---|---|---|
| GET | `/agent/station` | `{name, business, onShift: {ref, name, since} \| null, agents: [{ref, name}]}` (agents with a PIN) |
| POST | `/agent/station-token` | Token for the station's own room `station-{id}`, where `shift {state: "started", agentRef, name}` arrives while nobody is on shift |
| POST | `/agent/shift` | Optional PIN start: `{"agentRef": "asha", "pin": "4321"}` (`401` wrong PIN, `409 PIN_LOCKED`, `409 NO_PIN`, `409 SHIFT_BUSY`) |
| DELETE | `/agent/shift` | End my shift |

When a shift ends elsewhere (dashboard, idle time, end of day), the station gets a `shift` signal
`{deviceId, state: "ended", reason}` in the agent's lobby and is taken out of it.

## L8. Sign out
**Endpoint**: <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/agent/device`

The device is revoked (`SIGNED_OUT`); delete the key and refresh token from the vault.