Authentication & scopes
Personal access tokens, the scopes they carry, and what they can't do.
Personal access tokens
Scripts authenticate with a personal access token (PAT) in the Authorization header:
Authorization: Bearer srp_…- Create, list, and revoke tokens in Account → API tokens (open it). Each token has a name, optional expiry (30, 90, or 365 days, or never), and a set of scopes.
- The secret is shown once, when you create the token. SpendRock stores only a hash of it.
- The list shows each token's name, scopes, when it was created, when it was last used, and when it expires.
- A token acts as you. It sees the households you belong to and can do what you can do there, limited by its scopes.
- A revoked or expired token gets
401with the codeunauthenticated.
Bearer tokens only, never cookies
The API also accepts the web app's session cookie, but only from the web app itself. Calls from anywhere else, including the playground in these docs, must use a bearer token. Cross-origin requests never send or accept cookies.
Scopes
Every operation needs one scope. The reference shows it on each endpoint (and the spec has it as
x-spendrock-scope).
| Scope | Allows |
|---|---|
budget:read | Read months and their groups, items, funds, and favorites. |
budget:write | Create and reset months; add, edit, reorder, and delete groups and items; funds, favorites order, and harvest. |
transactions:read | List and read transactions, and merchant suggestions. |
transactions:write | Add, edit, delete, and restore transactions. |
households:read | List households, members, and invites. |
households:manage | Create, rename, delete, archive, and leave households; set the default; transfer ownership; remove members; send, revoke, accept, and decline invites. |
account:read | Read your profile (/me), settings, and sign-in methods. |
account:write | Change your settings. |
- A write scope includes its read scope (and
households:manageincludeshouseholds:read). - When creating a token, the presets are Read only (every
*:readscope) and Full access (every scope). You can also pick scopes one by one. - A call outside the token's scopes gets
403with the codeinsufficient_scope. The error names the scope it needs indetails.required_scope. For example:
{
"code": "insufficient_scope",
"message": "This token doesn't have the transactions:write scope.",
"details": { "required_scope": "transactions:write" }
}What tokens can't do
Some things need you, signed in, in a browser:
- Managing tokens. A token can't create, list, or revoke tokens.
- Changing your password.
These return 403 with the code session_required.
Sessions
The web app (a cookie) and the mobile app (a bearer session token from signing in) use sessions instead of personal access tokens. Sessions have every scope and aren't subject to the per-token rate limit. You don't need them for scripts; they're documented in the reference under auth for completeness.
No authentication
A few endpoints need no credentials: signing in, and looking up an invite by its link token. The
spec itself is public too (/openapi.json, /openapi.yaml).