Skip to content
BookendBookend Docs

Issue an API key

POST
/v1/api-keys
curl --request POST \
  --url http://localhost:8080/v1/api-keys \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "scopes": [ "example" ] }'

Creates a scoped API key; scopes is a non-empty subset of intake:write, status:read and evidence:read; and returns the plaintext key exactly once, in this response; only its SHA-256 hash is stored. The key is exchanged for a bearer token at POST /v1/auth/token. Administrators signed in as a user only (an admin API-key token gets 403); 400 for an empty name or unknown scope.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
string
scopes
Array<string>
Examplegenerated
{
  "name": "example",
  "scopes": [
    "example"
  ]
}

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json

The plaintext key is shown exactly once.

object
summary
required
object
id
required
string format: uuid
name
required
string
keyPrefix
required
string
scopes
required
Array<string>
createdAt
required
string format: date-time
revokedAt
required
null | string format: date-time
key
required
string
Examplegenerated
{
  "summary": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "name": "example",
    "keyPrefix": "example",
    "scopes": [
      "example"
    ],
    "createdAt": "2026-04-15T12:00:00Z",
    "revokedAt": "2026-04-15T12:00:00Z"
  },
  "key": "example"
}