Auth, scopes and exclusions
How an agent or script authenticates (OAuth 2.1 or a personal access token), what each scope allows, and how exclusions hide accounts and businesses in every query.
Two ways in
OAuth 2.1 for MCP clients. The client discovers everything from the server URL: /.well-known/oauth-protected-resource/mcp → the authorization server metadata → dynamic client registration (or a client metadata document) → PKCE (S256 only) → Truenote’s consent screen. Tokens are bound to the resource they were issued for (/mcp or /v1). Access tokens last an hour; refresh tokens 30 days, rotated on every use (a used one coming back revokes the whole family).
Personal access tokens for scripts and clients that don’t do OAuth. Connected agents → New access token: choose the scopes, the lifetime (7, 30, 90 or 365 days) and what it must never see. It’s shown once. Send it as Authorization: Bearer tn_pat_… to /v1 or /mcp.
Either way the connection is one grant, read fresh on every call.
Scopes
| Scope | Allows |
|---|---|
accounts:read | Accounts, balances, net worth history, buckets (with context:read) |
transactions:read | Transactions, spending summaries, recurring streams, plan vs actual (with context:read) |
investments:read | Holdings and investment transactions |
liabilities:read | Loans and cards: APR, minimum payment, due date |
context:read | Profile, entities, income sources, goals, notes, plans, the spending plan, tasks |
context:write | Write all of the above plus categories, rules, buckets’ ledger, Review decisions, transaction categories and entities, manual accounts; refresh or disconnect a bank. Implies context:read. |
documents:read | List and read uploaded documents (text masked: Social Security and long account numbers to the last four) |
documents:write | Upload a document (prepare_upload, POST /v1/documents) and edit what one is; delete one. Implies documents:read. |
get_overview needs no scope: it answers with the sections the grant allows and lists the rest as notIncluded.
New OAuth connections start read-only. A write tool called without context:write returns an error naming the scope; the client asks the person to allow more and you approve again on the consent screen.
Exclusions
A grant can exclude specific accounts, businesses (entities) or manual accounts. Exclusions are applied in SQL on every read, totals included (net worth, spending, the plan, goals, the tax set-aside), and checked on every write: an agent can’t categorize a transaction it can’t see, create a rule that would reach one, or delete a record that would change what it’s hidden from. Accounts you’ve hidden (or Truenote hid as unused) are excluded the same way unless the grant was given “Let it see them”.
Bank text isn’t filtered: a transaction on a visible account may name a hidden one in its description. The consent screen says so.
Limits
240 calls a minute per grant. Every call, allowed or refused, is written to the audit log with a summary of its arguments (ids and filters, never secrets).