Approve an agent's token request

token_requests.approve.post

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

Route

Approves the request with the code the agent showed you, for one of your households. The token is made as yours when the agent next polls, and is listed on your API tokens page, where you can revoke it. Five wrong codes deny the request. Needs a session.

Parameters#

Approve an agent's token request: parameters
Field	Description
`request_id`pathstringrequired	The request's ID, tkr_….

Request body#

JSON, as application/json.

Approve an agent's token request: request body fields
Field	Description
`user_code`stringrequired	The four digits the agent showed you.
`household_id`stringrequired	The household the token will reach. You must be a member.
`access`one of: read_only, read_writerequired	The access to grant: what the agent asked for, or read_only.

Response#

200 Approved.

Approve an agent's token request: response fields
Field	Description
`id`stringrequired	The request's ID, tkr_….
`name`stringrequired	What the agent calls itself. The agent wrote this; it isn't checked.
`description`stringrequired	What the agent says it wants the token for. The agent wrote this too.
`requested_access`one of: read_only, read_writerequired	The access the agent asked for.
`status`one of: pending, approved, denied, claimed, expiredrequired	pending waits for a person; approved waits for the agent to collect its token; claimed means it has; denied and expired are final.
`origin`string or nullrequired	Roughly where it was asked from, such as "Brooklyn, US". Null if unknown.
`created_at`string (date-time)required	When the agent asked, UTC.
`expires_at`string (date-time)required	When it stops being approvable or collectable, UTC.
`household_name`string or nullrequired	The household it was approved for, once approved.
`access`one of: read_only, read_write, null or nullrequired	The access granted, once approved.

Errors#

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

Approve an agent's token request: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`403`	Read error.code	Described above.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	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/approve' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
  "user_code": "example",
  "household_id": "hh_01K9BKQB60S07ENW3AHRZ6DMV2",
  "access": "read_only"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/token-requests/req_01K9BKNGK0ENW3AHRZ6DMV29GQ/approve", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    user_code: "example",
    household_id: "hh_01K9BKQB60S07ENW3AHRZ6DMV2",
    access: "read_only",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/token-requests/req_01K9BKNGK0ENW3AHRZ6DMV29GQ/approve HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json

{
  "user_code": "example",
  "household_id": "hh_01K9BKQB60S07ENW3AHRZ6DMV2",
  "access": "read_only"
}

Response, 200

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

{
  "id": "example",
  "name": "Example",
  "description": "example",
  "requested_access": "read_only",
  "status": "pending",
  "origin": "Brooklyn, US",
  "created_at": "2026-11-06T18:00:00Z",
  "expires_at": "2026-11-06T18:00:00Z",
  "household_name": "example",
  "access": "read_only"
}