---
title: "Claim a pairing token from the tapping phone"
method: POST
path: "/pairing/claim"
tags: ["Pairing"]
---

# Claim a pairing token from the tapping phone

`POST /pairing/claim`

## Request

- Base URL: `https://atk.tvarka.pro/v1`
- URL: `https://atk.tvarka.pro/v1/pairing/claim`
- Auth: none required

No Basic auth - authorized solely by the high-entropy `pairingToken`. One-claim, rate-limited,
stored hashed. Returns the request's `clientToken` and a minimal `summary` (purpose + label
only, never document contents).

## Request body

- AuthPairingClaimRequest
  - `pairingToken` string, required
  - `claimNonce` string: Optional; when the originating UI can pre-share it, binds the tap to the intended session.
  - `device` object
    - `platform` string
    - `appVersion` string
    - `deviceName` string

## Response `200`

Claimed.

- AuthPairingClaimResponse
  - `requestId` string, uuid, required
  - `purpose` 'auth' | 'sign', required
  - `clientToken` string, required
  - `status` 'pending' | 'awaitingCard' | 'awaitingCredentials' | 'finalizing' | 'done' | 'cancelled' | 'timeout' | 'deviceError' | 'pinBlocked' | 'cardRemoved' | 'certInvalid', required: Flat request status. Non-terminal - `pending`, `awaitingCard`, `awaitingCredentials`, `finalizing`. Terminal success - `done`. Terminal failure - `cancelled`/`timeout`/`deviceError`/`pinBlocked`/`cardRemoved`/`certInvalid`. `awaitingCredentials` is SDK-reported (CAN/PIN entry is out-of-band).
  - `summary` object: Minimal display context {purpose, provider, audience, label, format?} - never document contents.

## Other responses

- `404`: Unknown request.
- `409`: State/idempotency conflict (spent operation token, identity swap, terminal request).
- `429`: Too many requests.

---

[API](https://skmtc.dev/tvarka/apis/tvarka-atk-api.md) · [All operations](https://skmtc.dev/tvarka/apis/tvarka-atk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tvarka/apis/tvarka-atk-api/revisions/2ab888b16069?raw)