The SpeyBooks API supports two authentication methods. API keys are the recommended approach for programmatic integrations, scripts, and server-to-server communication. Bearer tokens (JWT) power the SpeyBooks portal and are available for session-based workflows.
All API requests must be authenticated. Unauthenticated requests return a 401 unauthorized error.
API key authentication
API keys are created and managed from the API Keys page in your SpeyBooks settings. Each key is scoped to a specific set of permissions and tied to your organisation.
Include the key in the X-API-Key header on every request.
API keys are prefixed with sk_live_ for production and sk_test_ for test mode. Keep them secret. Do not commit API keys to version control, embed them in client-side code, or share them in plain text. If a key is compromised, revoke it immediately from the API Keys settings page and create a new one.
Key properties
Each API key has a name (for your reference), a set of scopes controlling which resources it can access, and an optional expiry date. Keys with no expiry remain valid until revoked. The last four characters of the key are visible in the settings page for identification.
Bearer token authentication
Bearer tokens are issued by the login endpoint. The login flow returns an accessToken (valid for 15 minutes) and a refreshToken (valid for 7 days). If the user has two-factor authentication enabled, the initial login returns a temporary token instead, which must be exchanged via the TOTP verify endpoint.
The response includes a user object with the authenticated user's profile for immediate UI hydration.
Two-factor authentication (TOTP)
When TOTP is enabled on an account, the login endpoint returns requiresTotp: true and a tempToken valid for 5 minutes. To complete authentication, send the 6-digit code from the authenticator app to the TOTP verify endpoint with the temporary token in the Authorization header. On success, full access and refresh tokens are returned.
SpeyBooks TOTP follows RFC 6238 and is compatible with Google Authenticator, Authy, 1Password, and other standard TOTP apps. Two-factor authentication can be set up, enabled, and disabled from the account security settings or via the TOTP management endpoints.
Token refresh
Access tokens expire after 15 minutes. Before expiry, exchange the refresh token for a new access token. The refresh token itself is not rotated.
Password changes invalidate all existing refresh tokens across all devices. This is tracked via an internal token generation counter, so a compromised session cannot survive a password reset.
Using the token
Include the access token on subsequent requests using the Authorization: Bearer header.
When to use bearer tokens vs API keys
API keys are the right choice for most integrations. Use bearer tokens only when you need to authenticate as a specific user, for example in a custom frontend or a tool that requires per-user audit trails. API keys are simpler, support scoped permissions, and do not expire unexpectedly.
Scopes
API keys use scoped permissions to control access. Each scope follows the pattern resource:action, where action is either read or write. The write scope always implies read access.
| Scope | Grants access to |
|---|---|
invoices:read | List and retrieve invoices |
invoices:write | Create, update, delete, and finalise invoices |
contacts:read | List and retrieve contacts |
contacts:write | Create, update, and delete contacts |
transactions:read | List and retrieve transactions |
transactions:write | Create, update, categorise, and delete transactions |
accounts:read | List and retrieve chart of accounts |
accounts:write | Create, update, and delete accounts |
quotes:read | List and retrieve quotes |
quotes:write | Create, update, and delete quotes |
reports:read | Access financial reports (trial balance, P&L, balance sheet) |
organisation:read | Retrieve organisation details |
organisation:write | Update organisation settings |
bank-imports:write | Upload and confirm bank statement imports |
If an API key lacks the required scope for an endpoint, the API returns a 403 insufficient_scope error. The message field indicates which scope is needed.
Account lockout
The login endpoint tracks failed authentication attempts. After 5 consecutive failures, the account is locked for 15 minutes. The lockout response includes the time remaining. Successful login resets the failure counter.
Auth endpoints use constant-time responses to prevent user enumeration. Whether the username exists or not, the response timing and structure are identical.
Organisation context
Both authentication methods are scoped to a single organisation. API keys are created within an organisation and can only access that organisation's data. Bearer tokens carry the user's organisation context from login. There is no cross-organisation access.
Security recommendations
Keep API keys out of client-side code and version control. Use environment variables or a secrets manager. Create separate keys for separate integrations so you can revoke one without disrupting others. Use the narrowest scope that each integration requires. Set expiry dates on keys used for temporary or third-party access. Enable two-factor authentication on all accounts with API access. Monitor the API request log in your SpeyBooks settings to review key usage.