Skip to content

Authorization

Every time someone — a person, an app, or an AI agent — tries to do something in Hadron (open a memory, edit it, copy it, delete it), Hadron asks one question first: are you allowed to do that? This page explains, in plain language, how it decides.

Two different questions

Signing in answers “who are you?” — that's authentication. Authorization answers the next question: “what are you allowed to do?” They're separate. Being signed in doesn't mean you can do everything; it just tells Hadron whose permissions to check.

An analogy: badges, keys, and house rules

Picture an organization in Hadron as an office building, and each memory as a room inside it. Four ideas do all the work:

  • Your role is a badge. It's the everyday shorthand for what you can do. A "Reader" badge opens doors so you can look around; a "Contributor" badge also lets you rearrange the furniture; an "Admin" badge lets you manage the building.
  • A grant is a spare key. Sometimes one person needs to do one extra thing that their badge doesn't normally allow. Instead of upgrading their whole badge, you hand them a single key for that one door.
  • Guardrails are the building's house rules. The owner can post a rule — “nothing leaves this room” — that applies to everyone, no matter how good their badge or how many keys they hold. A house rule can only ever restrict; it never hands out new abilities.
  • Your own locker is yours alone. Some things are private to you. No badge, no key, and no building manager can open your locker. Only you.

The rest of this page is just those four ideas, spelled out.

Roles: the everyday shorthand

Most of the time, what you can do comes from your role in an organization. A role is simply a named bundle of abilities, so nobody has to hand out permissions one by one. Hadron's roles read like a ladder, each one including everything below it:

Role Can roughly…
Reader Look at the shared memories, but not change them.
Contributor Everything a Reader can, plus add and edit content inside the shared memories.
Admin Everything a Contributor can, plus create, copy, and remove whole shared memories, and manage the organization — settings and people.
Owner Full control of the organization.

For the vast majority of teams, roles are all you ever need. You give people a role, and their permissions follow.

Grants: the exception mechanism

Roles are tidy, but they can't express every rule — because a role is a bundle, and some rules are about a single ability or a single person.

Here's the classic example. Suppose you'd like an employee to read and edit one of your memories, but you're not comfortable letting them copy the entire thing into a different organization. You can't get there with roles alone: “copying a memory out” is really just “reading it, then re-creating it somewhere else,” so any badge good enough to read is good enough to copy. There's no “Contributor, but minus copying” badge — and inventing a new badge for every little exception quickly becomes unmanageable.

Hadron solves this with two moves that work together:

  1. Copying isn't part of the everyday badge. The Contributor role lets people read and edit, but doesn't include copying a whole memory into another organization. So by default, no ordinary contributor can do it.
  2. You hand out the ability only where it's needed — a grant. If one teammate genuinely needs to duplicate memories, you give them that single ability directly, attached to that one person — without promoting them to Admin.

So the simplest way to say what someone can do is:

Your permissions = everything your roles include, plus any individual grants you've been given.

Grants only ever add. They're the clean way to make an exception for one person without over-promoting them or loosening the rules for everyone else.

Guardrails: limits that can only take away

Grants add abilities. Guardrails do the opposite — they set a ceiling that trims what's allowed, and nothing can override them.

Back to the worry above. Say copying memories is normally fine in your organization, but there's one carefully-built memory you never want leaving. A guardrail is the shape of rule that expresses exactly this: “this may be read and edited, but never copied into another organization.” Because a guardrail only ever removes an ability — never hands one out — nothing out-votes it: not a fancy role, not a spare key, not even someone holding a grant to copy memories.

This is why Hadron keeps the two ideas separate:

  • Roles and grants decide what you can do (they add up).
  • Guardrails decide what you're capped at (they can only subtract).

What you're actually allowed to do is the overlap: an ability your roles or grants give you, that no guardrail takes away.

What guardrails cap today

The guardrails you can set today apply to an agent's run-time actions — whether an automation may send outbound messages, call external tools, or run at all. Memory-scoped caps like “never copy this one out” are the model's intended direction; they are not yet enforced on interactive copying, so don't rely on one to make a memory non-exportable right now. The Authorization reference has the precise, current scope.

Putting it together (the model)

An organization owner spent weeks curating a memory. She's happy for an employee to read and even improve it — so he's a Contributor (read + edit). But she never wants the whole thing copied into another company, so the guardrail she wants is no copying out.

In the model, that cap would hold for everyone — not because the employee lacks a role, but because a guardrail removes the ability for all principals, and no role or grant out-votes it. If she later decides one trusted colleague may duplicate it, she lifts the guardrail or makes a narrower exception — deliberately, and on the record. (As the note above says, memory-copy guardrails are the intended direction; today's enforced guardrails cap an agent's run-time actions.)

Your own private memory: the one absolute

There's one place none of the above reaches. Some memories are personal or private — a single person's own notes, history, or sensitive information. These belong to that one person, full stop.

No role opens them. No grant opens them. An organization Admin can't read them, the organization Owner can't read them, and even Hadron's own staff can't read them. This isn't a setting you can flip — it's a promise built into the platform. When a chatbot's end user shares something private, it stays theirs.

You can read more about this in Memory ownership and lifecycle and Memory access.

Impersonation: seeing what a teammate sees

There's one situation the badges-and-keys picture doesn't cover. A teammate says "I can't open that memory" — and you can. Nothing about your own permissions tells you why theirs differ. Guessing is slow, and asking them to screenshot their screen is worse.

So an organization Admin or Owner can temporarily look at Hadron as another member of that organization sees it. Back to the building analogy: you're not taking their badge or borrowing their identity — you're standing where they stand and looking in the same direction, so you can see which door is closed.

Four limits make that safe, and they're worth understanding because they're the whole design:

  • You can only look, never touch. Every action that would change something is refused outright while you're in that view. You diagnose, step back out, and then fix it as yourself. This means a support session can never be mistaken for the member's own work, and nothing lands in the audit trail under their name because of you.
  • You only see inside the one building. The view is scoped to the single organization you administer. If that person also belongs to two other organizations, those stay completely invisible — being an Admin somewhere doesn't quietly become a window into everywhere they happen to work.
  • Their locker stays shut. This is the important one: the previous section's promise is not weakened. Their personal and private memories, their AI chat transcripts, their mailbox and calendar and files, their own API keys — none of it is reachable, even though you are looking through their eyes. You see their organization access, which is what a support question is actually about. You never see their personal data. The locker has no key, and impersonation isn't one either.
  • It ends, and it's on the record. Sessions expire on their own, and you can end one at any moment. If your own authority changes mid-session — you lose the Admin role, or the person you're viewing is promoted above you — the session ends on the very next request rather than running to expiry, because every request re-checks both people's current roles rather than trusting what was true when the session began. Every session is written down: who, whom, which organization, when it started, when it stopped — and whether a person stopped it or authority was revoked. Those records are kept permanently.

The honest tradeoff: this is real power, and it's why it's restricted to the people who already administer that organization, capped at their own level (an Admin can't look through an Owner's eyes), and permanently logged. The alternative — support staff asking people to share credentials or screenshots — is worse on every axis: unbounded, unlogged, and it does expose personal data.

To use it, see Impersonate a member for support.

Sessions: your work is yours to close

A session is a record of a stretch of work — a coding session, a chatbot conversation, an automation run. Sessions get their own rule, and it's narrower than the badges above, for a reason worth spelling out.

You can always see your own sessions. Even one you started from the command line, outside any app. Without that, the odd situation would be that the person who did the work is the only one who can't look at the record of it. (One limit: this is your view of your own work. It isn't handed over during an impersonation session — that view stays read-only and stays out of a member's own records, exactly as the previous section describes.)

Your teammates can see your sessions, but they can't close them. Being on the same team is a reason to read the record — who's working on what, which session produced which pull request — and not a reason to reach into someone else's work and end it. So membership grants looking, never touching.

There's one more distinction hiding here, and it catches people out. An app can write to its own sessions. But when you connect through an app — picking it as the scope for what you're doing — you're still you, with an app selected; you haven't become the app. Choosing a scope isn't the same as holding the app's credentials. That's why two people working under the same app can each see the other's sessions and neither can close the other's.

The precise table — who reads, who writes, and what an update may change — is in the Authorization reference.

Who actually decides

One important detail: the Hadron server is always the one that decides. The apps you use — the web portal, the command-line tool, an AI agent, a third-party client — never make the real call. They only preview it.

That's why a button might be greyed out, or a tool might tell you up front that you can't do something: the app is trying to save you a wasted click by predicting the answer. But the genuine check happens on the server, every time, no matter which app you came from. If an app's prediction is ever out of date, the worst that happens is a button looks available and the server politely declines — never the reverse. Your data is guarded by the server, not by the friendliness of the app in front of it.

Why it's built this way

This might feel like a lot of moving parts for “who can do what.” Each piece earns its place:

  • Roles keep the common case effortless — assign a badge, done.
  • Grants let you make a precise exception for one person without loosening anything else, so “trust this one teammate with this one thing” doesn't force you to hand over the keys to everything.
  • Guardrails let an owner lock something down for everyone without rewriting anyone's role — the safe way to say “this never leaves.”
  • Private ownership gives end users a hard guarantee that their personal information is theirs alone.

The result is a system that's easy to run day to day, but still precise enough to answer the hard questions — like “let them edit it, but don't let them walk off with a copy” — that a simple list of roles never could.

What's next