Read a pairing request

Read a pairing request with an active person key before adding the new device.

GET/v1/device-requests/{code}

Access: Signed request
Client: Local or server client

Parameters#

Name	Location	Meaning
`code`Required	Path	Pairing code shown on the new device.

Send the common signed-request headers, including X-Nonce and X-Timestamp. A signed GET has no JSON body. Request signing

Request examples#

cURL

curl -fsS -X GET \
  -H "X-Public-Key: $PUBLIC_KEY" \
  -H "X-Signature: $REQUEST_SIGNATURE" -H "X-Nonce: $NONCE" -H "X-Timestamp: $TIMESTAMP" \
  "https://veil.rip/v1/device-requests/PAIRING_CODE"

Response#

HTTP 200application/json

The same pairing details as creation. Expired, incorrect and used codes all return 404.

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#

Signed GET requests use X-Nonce and X-Timestamp. No JSON body is sent.

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

HTTP	Code	Meaning and next step
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.
403	`key_mismatch`	The signing key does not have authority over this card or operation. Use an active device key with the required owner or member role.
404	`not_found`	The requested card, key, alias, code or resource was not found. Check the identifier. Temporary codes and previews may already have expired or been used.

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.

403

key_mismatch

The signing key does not have authority over this card or operation.

Use an active device key with the required owner or member role.

404

not_found

The requested card, key, alias, code or resource was not found.

Check the identifier. Temporary codes and previews may already have expired or been used.

Shared request errors

HTTP	Code	Meaning and next step
400	`invalid_nonce`	The signed-request nonce has an invalid format. Generate a fresh 16 to 128-character nonce using letters, digits, _ or -.
400	`invalid_signature_alg`	`X-Signature-Alg` is unsupported. Use a supported signing algorithm and matching key/signature encoding.
400	`invalid_timestamp`	The signed-request timestamp is not Unix milliseconds. Use an integer Unix timestamp in milliseconds and sign the corrected request.
401	`invalid_signature`	The HTTP request signature does not verify. Sign the exact method, path and body bytes, without changing them afterwards.
401	`missing_signature`	The request requires a device signature and its headers are missing or unreadable. Send `X-Public-Key`, `X-Signature` and the signed-request metadata. An API key does not replace a device signature.
401	`stale_timestamp`	The signed timestamp is outside the accepted clock window. Compare the server Date header with your clock, then generate a fresh nonce, timestamp and signature.
403	`key_banned`	The device signing key is suspended by Veil staff. Use an authorised active key or ask staff to review the restriction.
409	`replayed_nonce`	The signing key already used this nonce. Check whether the previous request succeeded before making a fresh signed request.
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.

Read this entry as JSON