Keys

Mint a new API key

Create a new API key for this account. The requested scopes must be a subset of the calling key's scopes (a key can never widen authority). Requires the keys:manage scope. The secret is returned exactly once.

post/api/v1/keys

Request

Base URL: https://volunteerreminder.com
URL: https://volunteerreminder.com/api/v1/keys
Auth: HTTP bearer

Request body

namestring required

A human-readable label so you can tell keys apart (e.g. the agent or script that will use it). 1–80 characters.

scopesScope[] required

The scopes to grant. MUST be a subset of the calling key's own scopes — a key can only ever mint a narrower-or-equal key, never a broader one. Duplicates are ignored.

Example request

{
  "name": "Claude food-pantry assistant",
  "scopes": [
    "read",
    "schedules:write"
  ]
}

Response

The key was created; the secret is in api_key (shown once).

idinteger required

The new key's id (use it to revoke).

namestring required

The label you supplied.

key_prefixstring required

Non-secret display prefix (vrk_ + 4 hex). Safe to log/show.

scopesScope[] required

The granted scopes, de-duplicated and in canonical order.

created_atinteger required

Epoch milliseconds (UTC).

api_keystring required

The full secret — SHOWN ONCE, right here. Store it now; it is never retrievable again. Send it on subsequent calls as Authorization: Bearer <api_key>.

Example response

{
  "key_prefix": "vrk_a1b2",
  "scopes": [
    "read"
  ],
  "api_key": "vrk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Changes

No recorded changes to this operation across all 1 revision of this API.