Grants and sectors

​

The six sectors

Postern sorts everything it holds into six sectors. The six are fixed: you cannot add one, rename one or split one. A grant names a sector, never a source. You choose what an agent reads when you create its key, not when you connect a source. Grant mail and that key reads every mail source you have now, and every one you add later. There is no way to grant one and withhold another. Disconnect a source and the grant does not change — the sector holds less. A key that holds none of a source’s sectors sees nothing, however many sources you connect.

​

Which sectors a sign-in turns on

Postern reads the scope list the provider returns with the token, not the list Postern asked for. It creates one connection per sector that list covers.

• Google — one sign-in becomes two connections, calendar and contacts, because the consent covered two sectors.
• Microsoft — Postern requests exactly Mail.Read, Calendars.Read, Contacts.Read and offline_access, and nothing else on any sign-in. That gives three connections. A consent that grants fewer gives fewer connections; sign in again and approve the whole set.
• WHOOP — read:recovery, read:sleep and read:workout each map to health. read:cycles, read:profile and offline map to no sector at all. A consent that returns none of the three health scopes creates no connection. The Console then answers WHOOP signed in, but granted no sectors. Check the scopes on your app, then sign in again. It can only report the connection it made. It cannot name the scope it did not get.

​

Two sources inside one sector

SimpleFIN arrives as one connection that holds every bank linked at the Bridge. The Console has no bank picker. SimpleFIN Bridge decides which banks it covers, and a bank added or dropped there appears or disappears on the next sync. The Sources row says so, with your own bank count in place of <n>: One link carries all <n> — which banks are in it is chosen at SimpleFIN Bridge ↗. Connect Plaid as well and the same account can arrive through both. Postern’s dedup engine matches on the institution’s domain plus the last 4 digits in the account name, and serves one account rather than two. It merges on its own only when both providers report a last 4. When one does not, it refuses to guess and asks Is this the same account, seen twice? Answer once with They’re the same account or Keep them separate, and it stays answered.

​

A granted sector with no source behind it

It is still granted, and it answers nothing. describe_context returns the sectors the key was granted, not the sectors that hold data. A query there comes back empty rather than refused, and fetch_live answers no active connection for sector '<name>'. Neither is a permission problem, and neither looks like one in the record.

​

What a grant covers

A grant works at the level of a whole sector. The same sector list gates reads and actions, with nothing per-action, per-tier or per-confirmation beneath it. The Console says so under the sector toggles: Each granted sector covers read and act across every provider in it. There is no confirmation step between an agent’s decision and your house, and a hosted agent asks no permission per call. Your instruction to the agent is the authorization. The sectors you tick at creation are the whole boundary between that agent and your data, for as long as the key lives.

​

Which sectors an agent can act in

The Mint a key form states it before you grant anything: A grant covers read and act, but only Home has a catalogue to act on today; Finance, Mail, Calendar, Contacts, Health are read-only. So no agent can move money through Postern, whatever its grant says. Google’s calendar and contacts are read-only twice over: the two scopes Postern requests are read-only, and the connector refuses to run an action. WHOOP is the same. That is a statement about connectors, not about the permission model. If a source adds actions later, keys that already hold that sector can use them. Nothing in a grant names an action, so Postern re-issues nothing and asks nobody again.

​

What the grant decides, tool by tool

Nothing is narrower than a sector. There is no per-connector, per-tool or per-call gating underneath a grant. Parameters and returns are on MCP tools. Refused, or quietly filtered carries the exact wording an agent gets back in each row of that table. An agent whose key opens finance is served the accounts, transactions and holdings in the local cache, plus each connection’s health. Once Plaid reports one, Postern also serves the date that bank’s consent expires.

​

Read a grant, and change it

To read what a key holds. Click Agents & keys, then the agent’s name. The lit toggles under Grants are its sectors. The line under the name reads never expires or expires in 60d. The section headed Recent passage lists that key’s last calls. To change the sectors. On that same page, tap a sector under Grants. Postern saves at once — there is no Save button. The hint under the toggles then reads Tap to toggle; the change applies at the agent's next session. To create a key. Click Agents & keys, then Mint a key. Type a name. Tap sectors under Grant which sectors. Pick a chip under Expires. Press Mint the key. Postern cannot show you this key again. It keeps a scrambled copy it can check against, never the key itself. One agent name holds one grant, and the record stores that name against every call the key makes. A second key under an existing name is a rotate — see Revoking, rotating, and removing. Through the API instead. POST /api/agents creates or replaces a grant, and PATCH /api/agents/<name> edits one. Both take a sectors array of strings and an optional expiresInDays between 1 and 3650. Both answer only on the machine Postern runs on. The deadline on the Expires row, and the four verbs that end a key, are on Agent keys.

​

Default-deny

A new key can reach nothing until you tick a sector. The sector list starts empty. A key with an empty list resolves, authenticates and connects, and then every sector check denies it. A freshly installed Postern answers on the agent port and grants nothing at all. Postern does not treat that as an error, and the Console does not block it: Mint the key needs a name and nothing else. The form says so three times. That is the intended shape rather than a defect, and it is why a connection that succeeds can still answer nothing. Two behaviours of the stored list matter if you write one through the API.

• A sector name Postern does not recognise is dropped, silently. Postern intersects the stored list with the six real sectors when the key resolves. A grant of finance and bogus grants finance and raises nothing. The endpoint checks only that the field is an array of strings. If a sector you wrote does not appear on the key, check its spelling against the six above.
• * expands to every sector. A stored grant of ["*"] resolves to all six at connection time. The Console cannot write one, because its toggles are built from the six named sectors. A wildcard grant can only arrive through POST /api/agents.

​

What Postern cannot express

A grant row holds a user, an agent name, a hash of the key, an array of sectors, a creation stamp, a revocation stamp and a deadline. Nothing else. So there is:

• no grant of one source inside a sector while another in the same sector is withheld;
• no per-object, per-field or per-row grant;
• no read-only grant — read and act travel together, and the only thing that limits action today is that five of the six sectors have no action catalogue behind them;
• no per-call approval, no confirmation tier, no rate limit, no budget, no time-of-day window;
• no per-sector deadline. One deadline covers the whole key;
• one grant per agent name, so two policies mean two agents.

The record is the compensating control for all of that. It tells you what an agent did, after it did it. It never stops anything. Per-user separation is real in the code. Every read is scoped to a user id, and a key that belongs to one user cannot reach another’s rows. But a self-hosted Postern seeds a single operator user and treats its id as a constant. Multi-user is future work, not shipped behaviour, and this page describes the single-user shape you have.

​

Confirm it works

• Console → Agents & keys lists the agent, and its line reads never expires or expires in <n>d.
• Click the agent. The toggles under Grants are lit for exactly the sectors you meant to grant.
• Ask the agent what it can see. It names those same sectors and no others.
• Ask the agent for something in a sector you did not grant. It is refused, and a row appears under Recent passage with deny.

​

If something went wrong

​

What you have now

The six sectors, which sectors a sign-in turns on, what one grant covers, and where every control that changes a grant lives in the Console. A grant covers read and act, and only home has anything to act on today. Nothing is granted until you tick it.

​

Next