Approvals

Ahena applies changes to your providers only after they're planned and, when they matter, approved by a person. Since migration 0011_approvals, Ahena itself enforces who can give that approval, not the CLI or the MCP server.

Which changes need the dashboard

A change needs approval in the Ahena dashboard, signed in when:

"Production" is the environment's effective kind: its kind is production, or one of its connections holds a live credential such as a Stripe sk_live_ key (environments). A "development" environment with a live Stripe key needs the dashboard for every change that isn't SAFE, and an admin to approve it; the plan and approval pages say Treated as production: holds a live Stripe key. The check runs when the change is approved and again when it's applied, so connecting a live key after approving from the CLI doesn't let the change through.

MANUAL steps are never applied by Ahena. The rule lives in needsBrowserApproval() (packages/core/src/services/approvals.ts), called with the effective kind, and every plan operation (and every action of a provider plan) carries a needsBrowserApproval flag. Ahena refuses a direct apply of such a change without the dashboard's approval (approval_required) whatever the client decided, and the MCP server then asks for it in the dashboard.

Why the browser

The CLI's token sits in ~/.config/ahena/credentials.json. An AI agent running on the same machine can read it and run ahena apply --yes. A prompt in the terminal or in the MCP client proves nothing to the server. A signed-in browser session (an httpOnly cookie held by the dashboard, optionally with two-factor sign-in) is something the agent doesn't have, so Ahena accepts approvals of changes that matter only from it.

How it works

1. The CLI or an agent asks: ahena apply approves a stored plan, or a direct apply (ahena configure, doctor --fix, drift --fix) is refused with approval_required and the CLI requests approval for exactly that change. Ahena re-plans against the provider and records an approval request with a summary it built itself (never text from the client).
2. The CLI opens https://app.ahena.io/approvals/<id> and waits (--no-wait prints the link and exits). An agent gets the link back as needs_human and tells you.
3. You approve or decline in the dashboard. Deciding needs the same permissions as approving directly: an admin for production, operations.destructive for billable or destructive changes. The request names the organization, project, environment, every operation with its classification and cost notice, and who asked (your terminal or an AI agent).
4. The CLI continues. Ahena applies only if:
   • the approval came from a browser session (approvedVia: "web"), within approvalTtlMs (60 minutes) of the decision;
   • for a direct apply, the approval is for this environment, this provider, this exact plan fingerprint and these actions, and hasn't been used (each approval is used once);
   • the provider's state still matches what was reviewed (the fingerprint is re-checked).

Pending requests expire after 60 minutes too. Everything is in the audit log: approval.request, approval.approve / approval.decline, approval.use, plan.approve (with approvedVia).

Agent sessions

ahena mcp creates an agent session (ahena_agent_…, 12 hours) from your CLI session and uses only that. The server marks its requests via: mcp from the session itself (the old x-ahena-via header is ignored). An agent session acts as you for reading, Doctor and planning, and it can ask for approval, but Ahena refuses it for:

• approving or declining requests, or approving a CLI sign-in (device code);
• revealing secret values;
• managing members, billing or the organization, deleting projects;
• creating CI tokens or further agent sessions.

What this doesn't cover

• An agent that controls your browser (computer use) or knows your password can act as you. Two-factor sign-in raises the bar for the password case.
• Non-production CONFIRMATION_REQUIRED changes are approved in the CLI; an agent with shell access to your CLI token can approve those. They're reversible, non-billable changes outside production by definition, and an environment holding a live Stripe key isn't "outside production". Live credentials of providers that can't report it (see environments) are only covered when you give the environment the production kind.
• CI tokens can't plan, approve or apply at all.