Make a personal API token

tokens.post

POST/api/v1/tokens

Route

Makes a token for your own scripts and agents to use one household as you, sent as Authorization: Bearer <token>. The token is in this response only; Rigel keeps just its hash. Commands it runs are recorded as coming from your token. Needs a session.

Request body#

JSON, as application/json.

Make a personal API token: request body fields
Field	Description
`household_id`stringrequired	The household it will reach. You must be a member.
`name`stringrequired	What it's for, 1 to 80 characters, such as "core2 import". 1 to 80 characters
`access`one of: read_only, read_writerequired	read_only runs queries and reads files; read_write also runs commands and uploads files.

Response#

201 The new token.

Make a personal API token: response fields
Field	Description
`(response)`anyrequired	No description.

Errors#

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

Make 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.
`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.

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/tokens' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
  "household_id": "hh_01K9BKNGK0ENW3AHRZ6DMV29GQ",
  "name": "core2 import",
  "access": "read_only"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    household_id: "hh_01K9BKNGK0ENW3AHRZ6DMV29GQ",
    name: "core2 import",
    access: "read_only",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "household_id": "hh_01K9BKNGK0ENW3AHRZ6DMV29GQ",
  "name": "core2 import",
  "access": "read_only"
}

Response, 201

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

null