Understanding Scopes & Permissions
Scopes define exactly what a connected service allows your agent to see or do. Instead of granting blanket access to a tool, Gatekeeper works scope by scope — so a connection can be as narrow or as broad as you choose.
How scopes work
When you connect a service, you'll see a list of specific, individually approvable permissions. Connecting Slack might offer scopes like:
- Read channel messages
- Send messages
- Read user profiles
- Manage channels
You don't have to approve all of them. Approving only "Read channel messages" means your agent can see conversations but can't post, invite users, or change settings — even if it tries.
Principle of least privilege
The safest setup is to grant only the scopes your agent's task actually requires, and nothing more. If you're not sure whether a scope is needed, start without it — you can always add it later if your agent hits a wall it genuinely needs to get past.
Scopes and policies are two separate gates
This is the single most common source of confusion in Gatekeeper, so it's worth being precise.
- Scopes set the outer boundary of what's possible. The service grants them when you connect.
- Policies decide what's allowed within that boundary. You write them, and they're evaluated on every request.
Both have to pass. Neither one overrides the other:
|
|
Policy allows it | Policy denies it |
|---|---|---|
| Scope granted | The action runs | Blocked — a policy decision, with a reason |
| Scope not granted | Blocked — the permission was never granted | Blocked |
The top-right cell is the one that surprises people. Granting write access doesn't override a policy that denies writes. If your agent is blocked on something you're certain you granted permission for, it's almost always a policy decision — see Troubleshooting Policy Denials.
The bottom-left cell catches people the other way: a permissive policy can't grant access the service never gave you. Loosening the policy won't help; you need to reauthenticate with the scope.
Telling them apart is easy once you know to look. A policy block returns a denial with a reason. A missing scope fails as a permission error from the service.
Updating scopes later
Business needs change, and so can your scopes:
- Go to Services and select the connected service.
- Choose Reauthenticate.
- Adjust the scope selection and confirm.
You don't need to disconnect first. Your existing policies and audit history are unaffected — your policies simply apply to whatever the new scope set allows.
Revoking access
Every grant Gatekeeper holds for you is listed under Sessions → Downstream, with the scopes it carries and a revoke control. Revoking clears the stored credential, and the next call to that service requires fresh consent.
Your policies and audit history survive revocation, so cutting off access doesn't cost you your records.