{"revision":"0ed62d2c742f8e20","language":"en","entry":{"id":"request-device","kind":"endpoint","group":"manage","title":"Request device pairing","method":"POST","path":"/v1/device-requests","paths":[],"summary":"Create a temporary pairing code for a new device’s public key.","response":"201 with code, display, key, alg, device, createdAt and expiresAt. The code lasts ten minutes.","parameters":[],"sample":"/v1/device-requests","access":"public-write","base":"directory","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":["400 invalid_json","400 invalid_name","400 invalid_parameter","409 key_already_used","413 payload_too_large","429 rate_limited","500 internal_error","503 busy"],"related":[],"sections":[{"kind":"code","language":"shell","code":"curl -fsS -X POST 'https://veil.rip/v1/device-requests' --json @request.json"}],"bodyFields":[{"name":"key","description":"The new device’s public key.","in":"body","required":true},{"name":"alg","description":"ed25519 or mldsa65-ed25519.","in":"body","required":false},{"name":"device","description":"A device name from 1 to 40 characters.","in":"body","required":true}],"live":false,"responses":[{"status":201,"contentType":"application/json","description":"201 with code, display, key, alg, device, createdAt and expiresAt. The code lasts ten minutes.","fields":[{"name":"code","type":"string","description":"Private eight-character pairing code."},{"name":"display","type":"string","description":"Code grouped for typing."},{"name":"key","type":"string","description":"Pending public key."},{"name":"alg","type":"string","description":"Signature algorithm identifier."},{"name":"ed25519","type":"string","description":"Ed25519 key or composite half, in hex."},{"name":"device","type":"string","description":"Requested device label."},{"name":"createdAt","type":"string","description":"Creation time."},{"name":"expiresAt","type":"string","description":"Expiry time, ten minutes after creation."}]}],"responseObjects":[],"errorFormat":"json","errorDetails":[{"status":400,"code":"invalid_json","description":"The body is not a JSON object, contains duplicate keys or has trailing data.","action":"Send one valid JSON object with `Content-Type` application/json.","scope":"endpoint"},{"status":400,"code":"invalid_name","description":"A name contains invisible, direction-control or unsupported format characters.","action":"Use a visible name in the accepted Unicode form and sign the corrected request.","scope":"endpoint"},{"status":400,"code":"invalid_parameter","description":"A path, query or body field is missing, malformed or outside its accepted range.","action":"Correct the field named in `error.message` before sending again.","scope":"endpoint"},{"status":409,"code":"key_already_used","description":"A device key already belongs to an identity and cannot be reused by another.","action":"Use the existing card or generate a fresh device key.","scope":"endpoint"},{"status":413,"code":"payload_too_large","description":"The request body exceeds this endpoint’s byte limit.","action":"Reduce the encoded body. API-key management accepts at most 8 KiB.","scope":"endpoint"},{"status":429,"code":"rate_limited","description":"An anonymous, signed-request or API-key allowance was exceeded.","action":"Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.","scope":"common"},{"status":500,"code":"internal_error","description":"An unexpected server error occurred. Internal details are not returned.","action":"Retry reads with bounded backoff. Check write results before sending a new signed operation.","scope":"common"},{"status":503,"code":"busy","description":"The application has reached a temporary concurrency or database limit.","action":"Wait `Retry-After` seconds and retry with bounded backoff.","scope":"common"}],"responseHeaders":[{"name":"Content-Type","value":"application/json","description":"Use the declared media type before choosing a parser."},{"name":"Date","value":"HTTP date","description":"Server time. Compare it with your clock when signing requests."},{"name":"Cache-Control","value":"no-store","description":"Do not persist private or temporary responses in a shared cache."},{"name":"Retry-After","value":"integer seconds, on rate_limited or busy","description":"Wait at least this long before retrying. Other 429/503 codes do not necessarily include it."}],"documentationUrl":"https://veil.rip/docs/request-device","supportsBrowserFetch":false,"browserMode":"local-or-server"}}