HOW GOVERNANCE WORKS
Watch a single action get refused, then allowed¶
This is already how your agent's plans run. Here we slow one operation right down so you can watch the machinery: the same call refused with no Grant, authorized by a Grant you set, allowed, and returned as a signed receipt.
The idea to hold onto: governance is a grant, not an if-statement. You never write access-control code. You set a Grant, and EKKA enforces it the same way over a database and over an AI model.
You need the setup from the quickstart
Signed in, an organization, and a running Enclave. If you have not done that yet, start with Build your first agent.
Your first governed action, by hand¶
A Gate is a governed boundary over something your agent might touch: a
database, an AI model, a tool. Nothing reaches it without a Grant and a
short-lived, signed token. You'll use a hosted postgres gate (instance
demoV1), a governed boundary over a database, and run one operation on the
customers resource.
4 · Try it with no Grant yet¶
Ask to list the customers resource before you've authorized anything:
BLOCKED RESOURCE_GRANT_DENIED
This agent holds no Grant for postgres:demoV1/customers.
Refused before any query ran. No data was touched.
What just happened
Nothing is allowed until you grant it. That's default-deny: with no Grant, EKKA refused. The block lands at the policy layer, before any I/O: no query was sent, nothing was read. The refusal is a decision EKKA records, not a silent error.
Preview a decision without running it
Add --check to any gate command to preview allow or deny without
executing the operation (no I/O, no cost):
5 · Authorize it with a standing Grant¶
ekka gate grant add --type postgres --instance demoV1 --resource customers \
--capability knowledge.postgres.read
A grant may only name a capability the agent already declares
Two different things have to be true, and they happen in this order. The declaration is what the agent asks for. The grant is which resource it may touch. A grant for something the agent never declared is refused:
It works above because creating a plan already widened the declaration for
you: while you own an agent and have never published it, ekka plan create
adds whatever that plan needs. To widen it yourself, run
ekka agent declare <agent-code> --add <capability> first, then grant.
What just happened
A Grant is durable policy you set once: which agent may do what, on which
gate and resource. It stays in force until you change it. This is the "grant,
not an if-statement" idea: you declared intent, you did not write a check. A
read grant covers the list operation you tried above.
The capability is the verb: knowledge.postgres.read says read, and a
read Grant covers the list you tried above. There is no separate access
level to set, the verb you name is the level. ekka gate list shows what
each gate offers.
You didn't name an agent: ekka resolves your agent for you, so you never
paste a UUID. On a team with more than one agent, add --agent <id> to grant
to a specific one.
6 · Run the same operation again¶
Nothing about the command changes. Only the policy did:
What just happened
Because a Grant now covers it, EKKA issued a short-lived, signed Gate Token from your Grant just for this operation. The gate verified that token and returned only what was in scope. Anything outside the token's scope is never handed back.
Under the hood: Grant vs Gate Token
The Grant is the durable policy (it lives until you revoke it). The Gate Token is issued fresh, per operation, and expires almost immediately. So the standing permission and the thing sent over the wire are two different objects: revoke the Grant and no new tokens can be issued, while any token already issued was only ever good for one scoped call.
7 · See the signed record¶
Every access, allowed and denied, is a signed Receipt. Look at the one you just created (use the run id printed by the previous command):
It answers with how many records checked out and that nothing has been changed, added or removed since the first one.
What just happened
receipts show prints the signed record of exactly what happened; receipts
verify re-checks the hash chain and every signature yourself, offline,
without trusting any dashboard. That is the difference between claiming your
AI was governed and being able to prove it.
8 · Governance is a live dial¶
Revoke the Grant, and the very same operation is blocked again. Re-grant, and it flows again, enforced instantly, with no code change:
ekka gate grant revoke <grant-id>
# ekka gate postgres list ... -> BLOCKED again
# ekka gate grant add ... -> ALLOWED again
What just happened
You changed what your agent can reach by changing a Grant, not by editing and redeploying code. That is the whole product in one move: governance is a grant, not an if-statement.
The same grammar over an AI model¶
An AI-model call is a governed operation too. The AI-model gate (type llm) is
just another gate, with the same grammar you just used on the database: deny,
grant, allow, receipt.
The shape is identical. You ask for a model completion:
ekka gate llm infer --instance ekka.ai_gateway --resource anthropic/sonnet-4 --input '{"prompt":"..."}'
With no Grant, it's blocked before the model is ever called. You authorize it with a Grant exactly like the database:
ekka gate grant add --type llm --instance ekka.ai_gateway --resource anthropic/sonnet-4 \
--capability llm.infer
Then the same call is allowed, and the model's answer comes back as a signed receipt you can verify.
What just happened
A database and an AI model are governed the exact same way: deny, grant, allow, receipt. One governance model, every gate. Nothing reaches a model without a Grant, and the model's answer is itself a receipt you can verify.
The four ideas you just used¶
The whole walkthrough rests on four words. Learn these and you know EKKA.
-
Gate
A governed boundary over a resource: a database, an AI model, a tool. An agent reaches a resource only through its gate, never around it.
-
Grant
Durable policy you set once: which agent may do what, on which gate and resource. Nothing is allowed by default. No Grant, no action.
-
Gate Token
A short-lived, signed permit issued per operation from a Grant. It scopes that one call to exactly what was authorized, then expires.
-
Receipt
A signed, verifiable record of every access, allowed and denied. Chained so tampering is obvious, and checkable offline without trusting a dashboard.
The one sentence to remember
Governance is a grant, not an if-statement. You set the Grant; EKKA issues the token, enforces the boundary at the gate, and signs the receipt, the same way over your data and over your models.