API Authentication

What it is

All API requests require authentication via an API key. Keys are created in the admin area, stored hashed (the raw key is shown only once on creation), and can have scoped permissions and an optional IP allowlist.

Headers

Send your API key in one of two ways:

Authorization: Bearer your_64_char_hex_api_key
# Or
X-API-Key: your_64_char_hex_api_key

Note: Some Apache/PHP-FPM setups strip the Authorization header. If Bearer auth fails, use X-API-Key.

Key format

API keys are 64 hexadecimal characters (32 bytes). Example: a1b2c3d4e5f6.... The key is validated by prefix lookup and password_verify() against the stored hash.

Permissions

Permissions are resource.action pairs. Examples:

• * – full access to all endpoints
• client.* – all client operations (create, read, update, delete)
• client.create, client.read, client.update, client.delete
• invoice.create, invoice.read, etc.

Resource names map from the URL path: /api/v1/clients → clients. Actions map from HTTP method: GET→read, POST→create, PUT/PATCH→update, DELETE→delete.

IP allowlist

If set, only requests from listed IPs are allowed. Empty allowlist = allow all. Stored as JSON array in api_keys.ip_allowlist.

Key rotation and revoke

Rotate: POST /api/v1/api-keys/{id}/rotate creates a new key with the same permissions and revokes the old one. The response includes the new key—store it immediately; it is not shown again.

Revoke: POST /api/v1/api-keys/{id}/revoke immediately invalidates the key. Use when a key is compromised or no longer needed.

Token expiry

API keys do not expire by default. Rotate keys periodically (e.g. every 90 days) or when staff leave. Use revoke for immediate invalidation.

Secure request example

curl -X GET "https://yourdomain.com/api/v1/clients" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Never put the API key in the URL. Use headers only. Store keys in environment variables or a secrets manager, not in source code.

How to set up

Go to Admin → API Keys. Create a key, copy it immediately (it is not shown again), set permissions and optionally an IP allowlist.