Skip to content

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.

Opens a handshake and mints the new device's session token, for the caller to seal. Needs a session.

Responses
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

Reads the owning device's own handshake. Needs a session.

No other account can observe it.

Parameters
Name In Type Description
id (required) path string (uuid)

Handshake id.

Responses
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

Deletes a sealed handshake, the claim: only a sealed one, so none is cut short. Needs no session.

Parameters
Name In Type Description
id (required) path string (uuid)

Handshake id.

Responses
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

Puts the claiming device's ephemeral public key. Needs no session.

The sealing device checks the proof.

Parameters
Name In Type Description
id (required) path string (uuid)

Handshake id.

Request body, application/json: DeviceLinkOffer

Responses
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

Reads the seal back, as it was put, for the claiming device to open. Needs no session.

Parameters
Name In Type Description
id (required) path string (uuid)

Handshake id.

Responses
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

Puts the owning device's ephemeral public key and the sealed payload, idempotently. Needs a session.

Parameters
Name In Type Description
id (required) path string (uuid)

Handshake id.

Request body, application/json: DeviceLinkSeal

Responses
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