> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuphos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permission grants

> Widen a connected role's cloud permissions from inside Nuphos — proposed by the agent, approved by an administrator, and never executed by the AI.

You keep your connected roles [least-privilege](/security/access-control), so
sooner or later the agent hits a wall: an `AccessDenied` on an action it needs to
finish a task. The old fix was to stop, open the cloud console, widen the role by
hand, and come back. **Permission grants** let an administrator do that widening
from inside Nuphos instead — without ever handing the AI the power to edit IAM.

## The permission-admin role

To enable this, an Administrator connects one extra binding — an AWS role or GCP
service account — and marks it as the account's **permission-admin** role. Its
only job is editing IAM: attaching policies to your other roles, granting roles to
your service accounts. It is deliberately *not* an operational role.

Three properties make it safe:

* **The AI agent never uses it.** It is excluded from the credentials an agent
  session can select, the credential middleware refuses to hand it to a session,
  and it is left out of any credential export. There is no path by which the agent
  operates as the permission-admin role.
* **Only administrators can act through it.** A permission change runs only when a
  team **Administrator** approves it.
* **It is scoped to IAM editing**, separate from the roles that do day-to-day
  work, so widening one role never depends on that role being able to widen
  itself.

<Note>
  A permission-admin role is a break-glass tool for controlled privilege
  escalation. Bind it once per account you want to manage this way; you don't need
  one for accounts you're happy to keep static.
</Note>

## How a grant happens

<Steps>
  <Step title="The agent hits a permission wall">
    While working with a normal operational role, the agent gets an
    `AccessDenied` on an action it needs.
  </Step>

  <Step title="The agent proposes a minimal change">
    Instead of trying to edit IAM itself (it can't), the agent files a
    **permission request** describing the smallest change that unblocks the work —
    attach one AWS managed policy, or grant one GCP predefined role — with a
    reason. Nothing is applied yet.
  </Step>

  <Step title="An administrator reviews and approves">
    A team Administrator reviews the request — the target role, the exact policy or
    role being added, and why — then approves or rejects it. Editors and Viewers
    can see the request but cannot approve it.
  </Step>

  <Step title="Nuphos applies it deterministically">
    On approval, **Nuphos** performs the IAM change through the permission-admin
    binding. The agent never performs the write. The result — applied or failed —
    is recorded on the request.
  </Step>
</Steps>

<Info>
  The agent proposes; a human approves; the platform executes. This keeps the AI
  strictly on the "propose" side of every privilege change.
</Info>

## Where requests appear

Permission requests show up in your team's [Plans](/agent/plans) library alongside
regular plans, so administrators have a single review queue:

* **Administrators** see every pending request for the team.
* The **requester** sees their own request and can copy its link to hand to an
  administrator — useful when the person who ran the agent isn't the one who can
  approve.

A request is also shown inline in the agent session that raised it, so an admin
working in that session can approve it on the spot.

## Setting it up

Bind the permission-admin role the same way you connect any account, then mark it
as the permission-admin binding for that account:

<Tabs>
  <Tab title="AWS">
    Create a second IAM role (for example `NuphosPermissionAdminRole`) with the
    same [OIDC web-identity trust policy](/connectors/aws) as your operational
    roles, and attach a policy that lets it edit IAM — `IAMFullAccess` is the
    simplest. At minimum it needs to attach and detach managed policies on your
    other roles (`iam:AttachRolePolicy`, `iam:DetachRolePolicy`) plus the
    supporting read actions. Bind it and mark it as the permission-admin role.
  </Tab>

  <Tab title="GCP">
    Create or reuse a service account and grant it a role that can manage project
    IAM (for example `roles/resourcemanager.projectIamAdmin`), with the same
    [impersonation setup](/connectors/gcp) as your connector. Bind it and mark it
    as the permission-admin service account.
  </Tab>
</Tabs>

<Warning>
  Give the permission-admin binding **only** IAM-editing power — don't reuse an
  operational role for it. Its whole value is being the one binding that can change
  permissions and the one binding the agent can never touch.
</Warning>

## Related

* [IAM trust model](/security/iam-trust) — how the underlying credentials work.
* [Approvals & audit](/security/approvals) — the broader human-in-control model.
* [Access control](/security/access-control) — roles, allow-lists, and per-session
  credential selection.