Skip to content

Connections and delegated access

An agent that reads your inbox needs access to your inbox. The obvious implementations are both bad: handing it your credentials, or giving the platform a service account that can read everyone's mail.

Hadron does neither. You connect your mailbox, and it stays yours. What an agent gets is a grant: a named, scoped, revocable delegation on that connection.

Two entities, and the split is the point

What it is Who owns it
Connection The link to an external mailbox, calendar or drive — the credentials and the provider The user who created it
Grant A delegation of some of that connection's operations to one App install Created and revoked by the connection's owner

The connection is the asset. The grant is a key cut for one lock, and you keep the original.

The grantee is an App install, never an Agent

A grant names an App, not the Agent inside it. That looks like a detail and is the load-bearing decision.

An Agent is a design — a role, a prompt, a set of tools — and the same Agent can be installed into two different Apps, in two different organizations, run by two different people. Those are two trust contexts, not one. If a grant named the Agent, trusting it in your own App would silently extend that trust to a stranger's install of the same Agent.

So the grant records the install. Trusting an assistant in your team's App says nothing about the same assistant somewhere else.

Cross-org delegation is deliberate, not an oversight: the connection's organization and the grantee App's organization may differ, and the grant row is the sole authority. That is how you let a contractor's App answer free/busy against your calendar without joining them to your org.

Scopes are per operation, and the map fails closed

A grant carries scopes — mail.read, mail.send, calendar.freebusy, calendar.read, drive.read — and every operation an agent can run is mapped to exactly one of them. Holding the scope is what makes the operation legal for a grantee.

The property worth understanding is what happens to an operation with no mapping: it requires a scope no grant can express, so no grantee can ever satisfy it. It stays owner-only, permanently, by construction.

That is not a gap in the table. It is the table's default, and it means adding a new operation is safe: forget to map it and it is owner-only, never open-to-everyone. The failure mode of forgetting points at "too strict".

Several mailbox operations are deliberately unmapped in v1 — deleting, moving, marking read, flagging, categorizing — and so is the one drive mutation. They are not missing scopes waiting to be added; they are operations the platform has decided an agent should not perform on your behalf yet.

calendar.freebusy is the shape to notice. A grantee holding it can ask whether you are busy at 3pm and cannot read what you are doing then. The scope is not a weaker version of calendar.read — it is a different question, and splitting them is what lets you answer scheduling requests without exposing your calendar's contents.

Only the owner grants, and only the owner revokes

There is no org-admin bypass. An organization administrator cannot grant access to your mailbox on your behalf, and cannot revoke a grant you made — the connection is yours, and administrative power over the org is not power over your personal credentials.

Revocation is a soft delete, and liveness is re-checked on every operation rather than cached. A revoked grant stops working immediately; it does not linger until something expires.

Grants may also carry an expiry, which is the better instrument when you know the end date — a contractor engagement, a two-week trial. An expiry you set once beats a revocation you have to remember.

Multiple live grants on the same connection and App are valid, and their scopes union. That is deliberate: you can add calendar.freebusy to an App that already has mail.read without editing or replacing the existing grant, and revoking one leaves the other standing.

What this is not

  • Not an agent capability toggle. Enabling a feature on an agent and delegating access to your mailbox are different acts, by different people, with different blast radii.
  • Not org-scoped. A grant is one user's connection delegated to one App install. Nobody else's mail comes with it.
  • Not permanent. Revoke or expire; the connection is unaffected either way.