API Keys

API keys provide programmatic access to the SpeyBooks API. Each key is scoped to an organisation and can be restricted to specific resources and operations using the scope system.

Key format

Keys follow the pattern sk_{environment}_{random} where environment is either live or test. The full key is shown exactly once at creation time — after that, only the last four characters (the "hint") are retrievable.

Security model

• Keys are hashed with Argon2id before storage — the plaintext is never persisted.
• Revocation is immediate and permanent.
• Rotation creates a new key and places the old key into a 24-hour grace period, allowing zero-downtime migration.
• All key lifecycle events are written to the audit log.

Scopes

Scopes control what a key can access. The hierarchy is:

• * — full access (default)
• read / write — global read or write across all resources
• {resource} — full access to a specific resource (e.g. invoices)
• {resource}:read / {resource}:write — granular per-resource

Scopes are immutable after creation. To change scopes, create a new key and revoke the old one (or use rotation).