Ask a person for a personal API token

token_requests.post

POST/api/v1/token-requests

Route
Public

For an agent with no token yet. Public, and limited to 5 a minute and 3 waiting at once per IP address. Show your person approval_url and user_code: they open the link signed in, type the code, choose the household and access, and approve. Then poll POST /api/v1/token-requests/{request_id}/claim with poll_secret every interval_seconds until it answers approved with the token. Keep poll_secret to yourself; it's what proves the token is yours. The request expires after 10 minutes.

Request body#

JSON, as application/json.

Ask a person for a personal API token: request body fields
Field	Description
`name`stringrequired	What you are, 1 to 80 characters, such as "Claude Code on perceptron". It becomes the token's name. 1 to 80 characters
`description`stringoptional	What you want the token for, up to 500 characters. Your person reads this before approving. at most 500 charactersDefault `""`
`access`one of: read_only, read_writeoptional	The access you need. The person can narrow read_write to read_only, never widen it. Defaults to read_write. Default `"read_write"`

Response#

201 The request is waiting for a person.

Ask a person for a personal API token: response fields
Field	Description
`request_id`stringrequired	The request's ID, tkr_….
`user_code`stringrequired	Four digits. Show them to your person; they type them to approve.
`approval_url`stringrequired	The page your person opens, signed in, to approve or deny.
`poll_secret`stringrequired	64 hex characters. Send it when polling; never show it to anyone.
`expires_at`string (date-time)required	When the request expires, UTC.
`interval_seconds`integerrequired	How long to wait between polls.

Errors#

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

Ask a person for a personal API token: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`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' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Claude Code on perceptron",
  "description": "",
  "access": "read_write"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/token-requests", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Claude Code on perceptron",
    description: "",
    access: "read_write",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "name": "Claude Code on perceptron",
  "description": "",
  "access": "read_write"
}

Response, 201

HTTP/1.1 201 Created
Content-Type: application/json
X-Request-Id: req_01K9BKNGK0ENW3AHRZ6DMV29GQ

{
  "request_id": "req_01K9BKNGK0ENW3AHRZ6DMV29GQ",
  "user_code": "example",
  "approval_url": "example",
  "poll_secret": "example",
  "expires_at": "2026-11-06T18:00:00Z",
  "interval_seconds": 1
}