Poll for the token you asked for

token_requests.claim.post

POST/api/v1/token-requests/{request_id}/claim

Route
Public

Public; the poll secret is the credential. Answers pending until your person decides. The first poll after they approve makes the token and returns it, once; later polls answer claimed. denied and expired are final: ask again if you still need a token. Limited to 30 polls a minute per request.

Parameters#

Poll for the token you asked for: parameters
Field	Description
`request_id`pathstringrequired	The request's ID, tkr_….

Request body#

JSON, as application/json.

Poll for the token you asked for: request body fields
Field	Description
`poll_secret`stringrequired	The poll_secret from asking.

Response#

200 Where the request stands, and the token once approved.

Poll for the token you asked for: response fields
Field	Description
`status`one of: pending, approved, denied, claimed, expiredrequired	approved carries the token; claimed means a poll already collected it.
`expires_at`string (date-time)required	When the request expires, UTC.
`interval_seconds`integerrequired	How long to wait before polling again.
`token`stringoptional	Only with approved: the token, tok_….<secret>. Shown only now; store it somewhere safe.
`token_id`stringoptional	Only with approved: the token's ID, tok_….
`household_id`stringoptional	Only with approved: the household it reaches.
`household_name`stringoptional	Only with approved: that household's name.
`access`one of: read_only, read_writeoptional	Only with approved: the access granted.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Poll for the token you asked for: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`429`	Read error.code	Described above.

Examples#

No call has been recorded for this operation yet, so this example is built from its schema. The values are placeholders.

Built from the schema

Not recorded from a real call: the fields are filled in from the schema, so the values are placeholders.

Request, curl

curl -X POST 'https://rigel.house/api/v1/token-requests/req_01K9BKNGK0ENW3AHRZ6DMV29GQ/claim' \
  -H 'Content-Type: application/json' \
  -d '{
  "poll_secret": "example"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/token-requests/req_01K9BKNGK0ENW3AHRZ6DMV29GQ/claim", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    poll_secret: "example",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/token-requests/req_01K9BKNGK0ENW3AHRZ6DMV29GQ/claim HTTP/1.1
Host: rigel.house
Content-Type: application/json

{
  "poll_secret": "example"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9BKNGK0ENW3AHRZ6DMV29GQ

{
  "status": "pending",
  "expires_at": "2026-11-06T18:00:00Z",
  "interval_seconds": 1,
  "token": "example",
  "token_id": "tok_01K9BKQB60S07ENW3AHRZ6DMV2"
}