API Keys

Scoped API keys let you grant limited access to your Sirr instance without sharing the master key. Each key has explicit permissions and an optional key prefix restriction.

Overview

The master key (SIRR_MASTER_KEY) is all-powerful — it can read, write, and delete any secret. Scoped API keys provide a way to delegate access with fine-grained control:

Permissions: Grant only the operations each consumer needs (read, write, delete, or admin)
Prefix scoping: Restrict a key to secrets under a specific path prefix (e.g. staging/*)
Auditable: Every API key operation is recorded in the audit log

Scoped API keys authenticate the same way as the master key — via the Authorization: Bearer <key> header. The server determines permissions based on which key is presented.

POST/keys

Create an API key

Create a new scoped API key. The key value is returned only once in the response — store it securely.

Required attributes

Name
name
Type
string
Description
A human-readable label for this key (e.g. "CI/CD pipeline", "staging reader").
Name
permissions
Type
string[]
Description
Array of permission strings. See Permission model below.

Optional attributes

Name
prefix
Type
string
Description
Restrict this key to secrets whose key starts with this prefix. Omit for access to all secrets (subject to permissions).
Name
expires_at
Type
integer
Description
Unix timestamp when this key expires. Omit for no expiration.

Request

POST

/keys

curl -X POST http://localhost:39999/keys \
  -H "Authorization: Bearer $SIRR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD pipeline",
    "permissions": ["read", "write"],
    "prefix": "ci/"
  }'

Response (201)

{
  "id": "key_a1b2c3d4",
  "name": "CI/CD pipeline",
  "token": "sirr_sk_7f3a...",
  "permissions": ["read", "write"],
  "prefix": "ci/",
  "expires_at": null,
  "created_at": 1700000000
}

The token field is only included in the creation response. Store it immediately — it cannot be retrieved again.

GET/keys

List API keys

List all API keys. The token field is redacted in list responses — only the key ID, name, permissions, and metadata are returned.

Request

GET

/keys

curl http://localhost:39999/keys \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "keys": [
    {
      "id": "key_a1b2c3d4",
      "name": "CI/CD pipeline",
      "permissions": ["read", "write"],
      "prefix": "ci/",
      "expires_at": null,
      "created_at": 1700000000,
      "last_used_at": 1700003600
    }
  ]
}

DELETE/keys/:id

Delete an API key

Revoke an API key immediately. Any requests using this key will receive 401 Unauthorized after deletion.

Path parameters

Name
id
Type
string
Description
The key ID returned when it was created.

Request

DELETE

/keys/:id

curl -X DELETE http://localhost:39999/keys/key_a1b2c3d4 \
  -H "Authorization: Bearer $SIRR_MASTER_KEY"

Response

{
  "deleted": true
}

Permission model

Each API key is granted one or more permissions that control what operations it can perform.

Permission	Allows
`read`	`GET /secrets/:key` — retrieve and decrypt secrets
`write`	`POST /secrets` — create new secrets
`delete`	`DELETE /secrets/:key` — delete specific secrets
`admin`	All operations including `GET /secrets` (list), `/prune`, `/audit`, `/webhooks`, and `/keys`

The admin permission is a superset that includes read, write, and delete. Only grant it to trusted consumers that need full access.

Common patterns

Use case	Permissions	Prefix
CI/CD pipeline	`read`, `write`	`ci/`
Read-only dashboard	`read`	—
Cleanup cron job	`delete`	—
Team lead	`admin`	`team-a/`
External contractor	`read`	`shared/`

Prefix scoping

When a prefix is set on an API key, the key can only operate on secrets whose key starts with that prefix.

# Key with prefix "staging/"
✅ staging/db-url      → allowed
✅ staging/api-key     → allowed
❌ production/db-url   → 403 Forbidden
❌ db-url              → 403 Forbidden

Prefix scoping is enforced server-side on every request. Attempting to access a secret outside the key's prefix returns 403 Forbidden without revealing whether the secret exists.

Prefix scoping works with all permissions. A key with ["read", "write"] and prefix "staging/" can only read and write secrets under staging/.