Authentication

SpeyBooks uses API keys to authenticate requests. All API requests must be made over HTTPS.

API keys

Your API key identifies your organisation and grants access to your data. Include it in every request:

curl https://api.speybooks.com/v1/invoices \
  -H "Authorization: Bearer sk_live_your_api_key"

Key types

Type	Prefix	Use case
Live	sk_live_	Production data
Test	sk_test_	Development and testing

Test keys operate on a separate dataset. No real financial data is affected.

Generating keys

1. Log in to app.speybooks.com
2. Navigate to Settings → API
3. Click Generate API Key
4. Select key type (Live or Test)
5. Copy your key immediately — it won't be shown again

Revoking keys

To revoke a compromised key:

1. Go to Settings → API
2. Find the key in the list
3. Click Revoke

The key is invalidated immediately. Any requests using it will return 401 Unauthorized.

Request format

All requests must include:

• Authorization header with your API key
• Content-Type: application/json for POST/PUT requests

curl -X POST https://api.speybooks.com/v1/contacts \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Ltd", "email": "accounts@acme.com"}'

Response format

All responses are JSON with consistent structure:

Success (2xx):

{
  "id": "cont_abc123",
  "name": "Acme Ltd",
  "email": "accounts@acme.com",
  "created_at": "2026-01-31T10:00:00Z"
}

Error (4xx/5xx):

{
  "error": {
    "code": "invalid_request",
    "message": "The 'email' field is required",
    "field": "email"
  }
}

Rate limits

API requests are rate limited to ensure fair usage:

Plan	Requests per minute
Sole Trader	60
Limited Company	120

When you exceed the limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Security best practices

1. Never expose keys in client-side code — API keys should only be used server-side
2. Use environment variables — Don't hardcode keys in source code
3. Rotate keys periodically — Generate new keys and revoke old ones
4. Use test keys for development — Keep live data separate

# Good: Environment variable
export SPEYBOOKS_API_KEY="sk_live_..."
curl https://api.speybooks.com/v1/invoices \
  -H "Authorization: Bearer $SPEYBOOKS_API_KEY"

Testing authentication

Verify your key is working:

curl https://api.speybooks.com/v1/organisation \
  -H "Authorization: Bearer sk_live_your_api_key"

A valid key returns your organisation details. An invalid key returns:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}