Scopes & Permissions

Overview

A connection's permissions are three separate things, and all three have to line up before a request succeeds:

1. Scopes — which areas of data this connection may touch, and whether it may change them.
2. The Allow changes switch — a per-connection opt-in that arms writes at all.
3. Privacy settings — which fields are stripped, and which accounts or categories are hidden.

Scopes and the switch decide whether an operation runs. Privacy settings decide what it can see and touch. This page covers all three.

The 16 scopes

These are the exact scope strings the authorization server advertises in scopes_supported, alongside the label the user sees on the consent screen. Read scopes are pre-checked at consent; write scopes are off by default.

Two mappings surprise people:

• Connections belong to sync:read, not accounts:read. Listing bank connections and reading aggregate sync health both need sync:read. If you are resolving a transaction all the way back to its bank, you need transactions:read, accounts:read, and sync:read.
• The debt payoff planner needs liabilities:read, and nothing more. It computes a plan and writes nothing, so it is a read despite being a POST.

Write scopes imply their read scopes

Holding a write scope automatically carries the read scope beneath it. You never need to ask for both.

Implication is transitive and is resolved server-side on every request, so a connection granted transactions:write can annotate without transactions.annotate:write ever appearing in its stored scope list.

Two sizes of transaction write

Transaction writes are deliberately split, because "help me tidy up my categories" and "you may change what I spent" are not the same request.

A connection holding only the narrow scope gets insufficient-scope on create, PATCH, and delete. That refusal is the point: it is a promise you can make to yourself in writing.

categories:write is separate again, and narrow by construction: it creates, renames, re-parents, restyles, and deletes custom categories. The seeded system categories are refused with 409 conflict — the rest of the app keys on that tree, so it is not a programmatic caller's to rewrite.

The two-switch rule

A write scope on its own does nothing. Every write requires both:

1. the relevant :write scope on the connection, and
2. the connection's Allow changes switch turned on.

They are set at different moments and answer different questions. Scopes say what kind of change is permitted; the switch says whether this connection may change anything at all. It is off by default on a new connection, and a user can flip it off later without touching the scope list — which instantly makes the connection read-only while leaving its configuration intact for when they turn it back on.

Handle writes-disabled distinctly from insufficient-scope in your client. They mean different things to the person who has to fix them: one is "ask for more permission", the other is "flip the switch you already have".

Privacy narrows what a scope reaches

Scopes are coarse — a whole area of data. Privacy settings cut into that area, and they are applied on Forbidden Finance's servers, after the scope check.

Redaction removes individual fields. There are 18 of them, and the list is fixed: a connection cannot ask for a field the registry does not name.

A redacted field is omitted from the payload — not blanked, not masked. Its id appears in the envelope's redacted_fields so you know something was removed.

Exclusion hides whole accounts or categories. An excluded row is absent from every list and from search, and asking for it by id returns the same not-found a nonexistent id returns.

What that means for writes

A write cannot change what the connection is not allowed to read. Attempt one and the whole request is refused with forbidden (403), carrying a single fixed message:

This connection's privacy settings hide a field this request would change.

It names no field. Which fields are hidden is itself part of the configuration, so a per-field answer would let a caller enumerate the privacy settings by probing writes one field at a time. The refusal is the same string every time, for every caller, in every case.

The practical consequence: read the connection's own capabilities from what it actually returns. If transaction.merchant shows up in redacted_fields, do not try to set a merchant.

Checking what you were granted

Nothing about a connection's scopes is secret from the connection itself. The most reliable check is the cheapest one: make the read you plan to build on and see whether it succeeds. A 403 with insufficient-scope means the scope is absent; a 200 whose envelope carries redacted_fields or filtered: true means the scope is present but narrowed.

For OAuth clients, the authorization server publishes the full scope vocabulary at https://api.403fin.io/.well-known/oauth-authorization-server under scopes_supported. Request the narrowest set that does the job — the consent screen shows the user exactly what you asked for, and a shorter list is approved more often than a long one.

Frequently Asked Questions

Do I need to ask for a read scope alongside its write scope?

No. A write scope carries its read scope automatically, and the implication is transitive — transactions:write reaches annotate and read without either being listed.

The user turned on Allow changes but my write still fails with insufficient-scope. Why?

The switch arms writes; it does not grant them. The connection also needs the specific :write scope for that operation. Have the user edit the connection's scopes under Settings > AI & API Connections.

Can I request a scope the user did not grant, and get it added?

No. A connection receives exactly what the user approved at consent, and it cannot widen its own access. Changing scopes is something the user does in the app.

Why did my write get a 403 with no field named?

A field the request would have changed is hidden by this connection's privacy settings. The message deliberately does not say which one — naming it would let a caller map the hidden set by probing. Check the envelope's redacted_fields on a read of the same resource.

Is there a scope for moving money, or for bank credentials?

No. There is no such operation on this API at all. The write surface is transactions, categories, budgets, and goals — nothing reaches payments, transfers between institutions, or the credentials behind a bank connection.

Related Articles

Need more help? Contact us at [email protected].