Approve a reveal
The console page where a person approves or denies a coding agent's request to open one value, within ten minutes.
Path: /approvals/[id]. An agent running penv reveal KEY gets an approval id and exit code 4. We never put the value in that answer.
A harness running penv hook (Claude Code, Cursor, Gemini, Cline, Windsurf) lets
penv reveal through to this page from 1.0.0-beta.4. In 1.0.0-beta.3 the hook refuses penv reveal
before it runs, so no request reaches this page from there.
Flow: keep agents out of .env.
/approvals lists open change requests and elevated access.
Fields
| Field | Content |
|---|---|
| Key | Path and name requested. Never a value |
| Project and environment | Where the key lives |
| Who asked | The person whose session the agent runs under |
| Device, harness, session | The machine, the tool driving it, the session id |
Harness and session are CLI-sent labels, truncated at 128 characters; they authorize nothing and trace which keys one session touched. An answered, expired or foreign-workspace request reads "No such request", so the page never confirms that an approval exists.
Expiry and single use
| Rule | Behavior |
|---|---|
| Window | 10 minutes from filing, for the whole exchange; an uncollected approval expires too |
| Spend | Once. We claim the row before decryption, so two redemptions cannot both open the value |
| Re-check | We read your permission and step-up at the moment you answer |
Refusal codes the agent receives: approval codes.
Read the key name and the session before you approve. Your approval opens one specific value to whatever drives that session.
Required permissions
Slugs: roles and permissions. Step-up: security and MFA. We check the permission before step-up.
| Action | Needs | Step-up | Recorded as |
|---|---|---|---|
| Open the page | secret:reveal at that environment | No | not recorded |
| Approve | secret:reveal at that environment | Yes | secret.reveal_approved |
| Deny | secret:reveal at that environment | Yes | secret.reveal_denied |
Audit entries
| Entry | Actor | Meaning |
|---|---|---|
secret.reveal_requested | Requester | The agent's ask |
secret.reveal_approved or secret.reveal_denied | Approver | Your answer |
secret.read | Requester | The read, in the name of the credential that opened it |
secret.reveal | Approver, beside the session | Who allowed it |
secret.reveal_refused | Requester | A turned-away redemption, with its state: pending, denied, expired or already spent |
We settle expired requests without an entry; the secret.reveal_refused a late agent receives is the record.
Next: workspace name and region.