API reference: device-links
Signing in a new device from one already signed in, without the password. The signed-in device opens a handshake and shows it as a QR code. The new device offers an ephemeral key, which the signed-in device checks against the secret in the QR code before sealing a session and the account’s keys to it. The server relays only public keys and sealed payloads.
POST /v1/device-links
Opens a handshake and mints the new device's session token, for the caller to seal. Needs a session.
| Status | Description | Body |
|---|---|---|
| 201 | Handshake opened. | DeviceLinkStart application/json |
| 401 | No valid session token | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
GET /v1/device-links/{id}
Reads the owning device's own handshake. Needs a session.
No other account can observe it.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Handshake id. |
| Status | Description | Body |
|---|---|---|
| 200 | Handshake status. | DeviceLinkStatus application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No such handshake | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
DELETE /v1/device-links/{id}
Deletes a sealed handshake, the claim: only a sealed one, so none is cut short. Needs no session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Handshake id. |
| Status | Description | Body |
|---|---|---|
| 204 | Handshake consumed | |
| 400 | The request is malformed | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
PUT /v1/device-links/{id}/offer
Puts the claiming device's ephemeral public key. Needs no session.
The sealing device checks the proof.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Handshake id. |
Request body, application/json: DeviceLinkOffer
| Status | Description | Body |
|---|---|---|
| 204 | Offer accepted | |
| 400 | The request is malformed | Problem application/problem+json |
| 409 | Expired or out of order | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
GET /v1/device-links/{id}/seal
Reads the seal back, as it was put, for the claiming device to open. Needs no session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Handshake id. |
| Status | Description | Body |
|---|---|---|
| 200 | Sealed payload. | DeviceLinkSeal application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 404 | Not sealed yet, or expired | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
PUT /v1/device-links/{id}/seal
Puts the owning device's ephemeral public key and the sealed payload, idempotently. Needs a session.
| Name | In | Type | Description |
|---|---|---|---|
id (required) | path | string (uuid) | Handshake id. |
Request body, application/json: DeviceLinkSeal
| Status | Description | Body |
|---|---|---|
| 204 | Payload sealed | |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No such handshake on this account | Problem application/problem+json |
| 409 | Expired or out of order | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |