Authentication

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

API keys identify your organisation, are scoped to specific permissions, and grant access only to the resources and actions you allow.

API keys

Include your API key in the Authorization header using the Bearer scheme:

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

Key types

TypePrefixUse case
Livesk_live_Production data
Testsk_test_Development and testing

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

Scoped permissions

API keys support 17 granular scopes in resource:action format. A key with invoices:read can list and retrieve invoices but cannot create, update, or delete them. When a key attempts an operation outside its scopes, the API returns 403 Forbidden with the required scope in the error message.

Available scopes

ScopeDescription
accounts:readList and retrieve chart of accounts
accounts:writeCreate, update, delete accounts
contacts:readList and retrieve contacts
contacts:writeCreate, update, deactivate contacts
invoices:readList, retrieve, and download invoices
invoices:writeCreate, update, delete, send invoices
quotes:readList and retrieve quotes
quotes:writeCreate, update, delete, convert quotes
transactions:readList and retrieve transactions
transactions:writeCreate, categorise, reconcile transactions
reports:readGenerate P&L, balance sheet, VAT returns
bank-imports:readList and retrieve bank imports
bank-imports:writeUpload, confirm, delete bank imports
directors:readList directors, DLA balances, snapshots
directors:writeAdd, update, resign directors, manage DLA
dividends:readList dividends, board minutes, summaries
dividends:writeDeclare, pay, void dividends

Scope recommendations

Use caseRecommended scopes
Reporting dashboardinvoices:read, reports:read, contacts:read
Invoicing automationinvoices:write, contacts:read
Bank import scriptbank-imports:write, transactions:read
Full accessAll scopes (or omit scopes to grant everything)

Generating API keys

Via the web portal

  1. Log in to app.speybooks.com
  2. Navigate to Settings > API Keys
  3. Click Generate API Key
  4. Enter a descriptive name and select scopes
  5. Copy the key immediately - it will not be shown again

Via the API

curl -X POST https://api.speybooks.com/v1/api-keys \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reporting dashboard",
    "scopes": ["invoices:read", "reports:read", "contacts:read"]
  }'

The full key value is returned once in the response. Store it securely. It cannot be retrieved again - only the prefix (first 8 characters) is visible after creation.

Rotating API keys

To rotate a key without downtime:

curl -X POST https://api.speybooks.com/v1/api-keys/key_1/rotate \
  -H "Authorization: Bearer sk_live_..."

This generates a new key with the same name and scopes, and revokes the old one. Update your application with the new key from the response.

Revoking API keys

To revoke a compromised or unused key:

curl -X DELETE https://api.speybooks.com/v1/api-keys/key_1 \
  -H "Authorization: Bearer sk_live_..."

The key is invalidated immediately. All subsequent requests using that key return 401 Unauthorized.

Idempotency keys

For mutation requests (POST, PATCH, PUT, DELETE), include an Idempotency-Key header to make the request safely retryable:

curl -X POST https://api.speybooks.com/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: inv-feb-acme" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If the same idempotency key is sent again within 24 hours, SpeyBooks returns the original response instead of creating a duplicate. If the original request failed with a 5xx error, the key is released and can be retried.

Idempotency keys are optional but strongly recommended for any automated workflow.

Request requirements

All API requests must include:

  • An Authorization header with a valid Bearer token
  • Content-Type: application/json for POST, PUT, and PATCH requests

Response format

All responses use a consistent JSON envelope:

{
  "success": true,
  "data": { ... },
  "meta": { "total": 47 }
}

Error responses include a machine-readable code, a human-readable message, and an optional field for validation errors:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The 'email' field is required",
    "field": "email"
  }
}

Rate limits

Requests are rate limited per endpoint to ensure fair usage.

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when requests may resume.

Security best practices

Never expose API keys in client-side code API keys are intended for server-side use only. Never include them in browser JavaScript, mobile apps, or public repositories.
  • Use environment variables - store keys in environment variables, not source code
  • Scope keys to minimum permissions - a reporting key shouldn't be able to delete contacts
  • Rotate keys periodically - generate new keys and revoke old ones to limit exposure
  • Use test keys for development - keep production data isolated from testing
export SPEYBOOKS_API_KEY="sk_live_..."
curl https://api.speybooks.com/v1/invoices \
  -H "Authorization: Bearer $SPEYBOOKS_API_KEY"

Testing authentication

Verify that your API key is valid by fetching your organisation:

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

A valid key returns your organisation details. An invalid or missing key returns 401 Unauthorized.

Related endpoints