Skip to main content

The four objects

Everything you do in Permaura is arranging four objects. Learn these once and the whole console reads like a sentence.

Connection​

A connection is one configured integration: Braintree production, GitHub as @you, a fal.ai endpoint. It holds three things:

  • a credential (an API key, or an OAuth token) that is sealed on your gateway and never shown again,
  • the capabilities it exposes (the actions an agent could take — braintree.transactions.refund, github.pull_requests.create),
  • its health and a kill switch to disable it instantly.

A connection on its own grants nothing. It's the what could be done, not who may do it. You create connections on the Connections page — see Add a connection.

Policy​

A policy is a reusable permission template scoped to one connection. It is just three lists of actions:

  • Allow — may run.
  • Needs approval — runs only after a human says yes.
  • Deny — never runs, even if something else would allow it.

A policy names no agent and has no expiry. It's a rule you can reuse — "Read-only GitHub", "Refunds under review" — and attach to as many agents as you like.

Grant​

A grant is what actually hands out access: it binds policies to agents. A single grant can:

  • reference one or more policies (which may span several connections),
  • target specific agents or all agents,
  • carry budgets (a cap on calls, per period — day, week, month, or overall),
  • carry an expiry, and an enabled/paused switch you can flip at any time.

Every account has exactly one Default grant — the baseline that every approved agent inherits. You can pause it, but not delete it. Layer more grants on top for specific agents or higher-risk connections.

Grants read like a sentence: this agent may use these actions on this connection, until this date

Agent​

An agent is any AI client that talks to your gateway over MCP — Claude Code, Codex, Cursor, ChatGPT. You don't create an agent record by hand. The agent proves who it is by connecting, shows up Pending, and you approve it. Identity is the live session, not a name you typed.

Approving an agent lets it connect. It still can't do anything until a grant allows it — see Connect an agent and Grant access.

How a request is decided​

When an agent asks to run an action on a connection, the gateway resolves it in order:

  1. Does the connection exist and is the capability enabled? If not → deny.
  2. Gather every enabled grant that targets this agent (or all agents) whose policy is scoped to this connection.
  3. Across those policies, the strictest wins: deny beats needs-approval beats allow.
  4. Apply the grant's budget and expiry.
  5. If nothing explicitly allowed it → deny by default.

That ladder is why a stray or injected instruction can't escalate: an agent can ask for anything, but only your grants decide what runs.

Where each object lives in the console

Connections and Agents live under Access. Policies, Grants, and Approvals live under Control. The Console tour walks through each.