Request device pairing

Create a temporary pairing code for a new device’s public key.

POST/v1/device-requests

Access: Creates temporary data
Client: Local or server client

JSON body#

Name	Location	Meaning
`key`Required	JSON	The new device’s public key.
`alg`	JSON	ed25519 or mldsa65-ed25519.
`device`Required	JSON	A device name from 1 to 40 characters.

Request examples#

cURL

curl -fsS -X POST 'https://veil.rip/v1/device-requests' --json @request.json

Response#

HTTP 201application/json

201 with code, display, key, alg, device, createdAt and expiresAt. The code lasts ten minutes.

Field	Type	Meaning
`code`	`string`	Private eight-character pairing code.
`display`	`string`	Code grouped for typing.
`key`	`string`	Pending public key.
`alg`	`string`	Signature algorithm identifier.
`ed25519`	`string`	Ed25519 key or composite half, in hex.
`device`	`string`	Requested device label.
`createdAt`	`string`	Creation time.
`expiresAt`	`string`	Expiry time, ten minutes after creation.

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	Use the declared media type before choosing a parser.
`Date`	`HTTP date`	Server time. Compare it with your clock when signing requests.
`Cache-Control`	`no-store`	Do not persist private or temporary responses in a shared cache.
`Retry-After`	`integer seconds, on rate_limited or busy`	Wait at least this long before retrying. Other 429/503 codes do not necessarily include it.

Usage notes#

Creating codes is limited to 10 per hour per IP. Reading pairing codes is limited to 5 per minute per IP and requires an active person key.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP	Code	Meaning and next step
400	`invalid_json`	The body is not a JSON object, contains duplicate keys or has trailing data. Send one valid JSON object with `Content-Type` application/json.
400	`invalid_name`	A name contains invisible, direction-control or unsupported format characters. Use a visible name in the accepted Unicode form and sign the corrected request.
400	`invalid_parameter`	A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in `error.message` before sending again.
409	`key_already_used`	A device key already belongs to an identity and cannot be reused by another. Use the existing card or generate a fresh device key.
413	`payload_too_large`	The request body exceeds this endpoint’s byte limit. Reduce the encoded body. API-key management accepts at most 8 KiB.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON