Authentication
Every WhiteBooks API call is authenticated with OAuth 2.0. You exchange your application credentials for a short-lived bearer token, then send that token with each request.
Your credentials
After signing up you receive three values. Treat the secret like a password.
| Credential | Sent as | Purpose |
|---|---|---|
x-api-key | Header | Identifies and rate-limits your application. |
client_id | Header | Public identifier for the OAuth client. |
client_secret | Header | Private secret used only to mint tokens. |
client_secret in browser or mobile code. Mint tokens from your backend and pass only the resulting bearer token to clients if needed.1 · Request an access token
Call the authentication endpoint with your credentials in the headers:
A successful response returns an access_token, a token_type of Bearer, and expires_in seconds.
2 · Authenticate requests
Attach the token in the Authorization header (and keep sending x-api-key) on every call:
Token lifetime & refresh
Access tokens are valid for one hour (expires_in: 3600). When a token expires the API returns 401 Unauthorized — request a new token and retry. Our official SDKs cache and refresh tokens for you automatically.
Production security
Production accounts can layer on additional controls:
- TLS 1.2+ is enforced on all endpoints (TLS 1.3 preferred).
- IP allow-listing restricts which addresses may use your keys.
- SHA256-RSA request signing adds payload integrity for sensitive flows.
- Role-based access control scopes what each key can do.
Common auth errors
| Status | Meaning | Fix |
|---|---|---|
401 | Token missing, invalid, or expired | Request a fresh token and retry. |
403 | Key lacks permission or IP not allow-listed | Check RBAC scopes and allow-list. |
429 | Rate limit exceeded | Back off and retry after the reset window. |