Authentication #
Microbooks is a full OAuth 2.0 authorization server, following OAuth 2.1 practice for third-party apps: authorization code with PKCE, rotating refresh tokens, no implicit flow. Every request to the API is authenticated with a bearer token — a signed JWT issued by the auth service and verified by the resource APIs against the platform’s published keys (JWKS).
The password grant is also enabled, but only as the mechanism behind the first-party login endpoint. It is not the path to use for an integration: use a personal access token or the OAuth flow instead.
There are three ways to get a token. Pick the one that matches what you are building:
| You are building… | Use | Where to start |
|---|---|---|
| A script, CI job, or the MCP server | Personal access token | Personal access tokens |
| An app that accesses other users’ books | Authorization code + PKCE | OAuth flow |
| A quick experiment against your own account | Password login | Login |
Scopes #
Tokens carry scopes, and the resource APIs enforce them: GET requests need the :read scope, writes need :write.
| Scope | Grants |
|---|---|
books:read | Read accounting records |
books:write | Create and update accounting records |
payments:read | Read payment records |
payments:write | Create and update payment records |
An account can only grant the scopes it is entitled to — a standard account gets the books:* scopes.
Token lifetimes #
| Token | Lifetime | Notes |
|---|---|---|
| Access token | 15 minutes | Sent as Authorization: Bearer <token> |
| Refresh token | 30 days | Rotates on every use — the old one is revoked when redeemed |
| Personal access token | 1 year | Long-lived by design; revoke any you stop using |
Because access tokens are short-lived, any long-running integration must either use a personal access token or implement refresh.