{"revision":"0ed62d2c742f8e20","language":"en","entry":{"id":"link-state","kind":"endpoint","group":"manage","title":"Read a private proof state","method":"GET","path":"/v1/links/{state}","paths":[],"summary":"Resume a proof with its secret state token.","response":"The challenge or verified grant, expiry and transfer information. Treat this response and the state as private.","parameters":[{"name":"state","description":"The private 64-character hexadecimal state returned by start.","in":"path","required":true}],"sample":"/v1/links/PROOF_STATE","access":"private-code","base":"directory","notes":[],"errors":["400 invalid_parameter","404 not_found","429 rate_limited","500 internal_error","503 busy"],"related":[],"sections":[{"kind":"code","language":"shell","code":"curl -fsS 'https://veil.rip/v1/links/PROOF_STATE'"}],"live":false,"responses":[{"status":200,"contentType":"application/json","description":"The challenge or verified grant, expiry and transfer information. Treat this response and the state as private.","fields":[{"name":"state","type":"string","description":"Private proof-session state."},{"name":"identity","type":"integer","description":"Target card number."},{"name":"platform","type":"string","description":"Platform identifier."},{"name":"method","type":"string","description":"Proof method."},{"name":"status","type":"string","description":"pending, returned, verified, used or expired."},{"name":"expiresAt","type":"string","description":"Session expiry time."},{"name":"subject","type":"string | null","description":"Verified normalised account identifier."},{"name":"display","type":"string | null","description":"Verified display name."},{"name":"grant","type":"string | null","description":"Single-use signed grant after verification, until used."},{"name":"grantExpiresAt","type":"string | null","description":"Grant expiry time."},{"name":"challenge","type":"string | null","description":"Public challenge instructions."},{"name":"claimed","type":"string | null","description":"Account requested at the start, for methods that require it."},{"name":"holder","type":"integer | null","description":"Current card holding the verified account."},{"name":"waitDays","type":"integer | null","description":"Takeover cancellation period if another card holds it."},{"name":"takeoverOpen","type":"boolean | null","description":"Whether a takeover is already open."}]}],"responseObjects":[],"errorFormat":"json","errorDetails":[{"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":404,"code":"not_found","description":"The requested card, key, alias, code or resource was not found.","action":"Check the identifier. Temporary codes and previews may already have expired or been used.","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/link-state","supportsBrowserFetch":false,"browserMode":"local-or-server"}}