secrets
ak secrets request
Ask the operator for access to a secret without releasing it.
Use ak secrets request from an agent that has found a credential with
ak secrets search and ak secrets describe
and wants access before using it. The request waits in the same inbox a refused
resolve files into, for the operator to answer with ak secrets approve.
A request never releases or reads a value, never writes a grant, and never spends an allow-once; only the operator's answer grants anything.
Usage
ak secrets request <ref> [--purpose <text>] [--project <slot>] [--session <id>] [--exec <program> --env <VAR>]Exactly one ref is required.
| Flag | Default | Description |
|---|---|---|
--purpose <text> | empty | Why the secret is needed; shown to the operator and matched literally by the grant. At most 200 characters. |
--project <slot> | the AK project containing the current directory | Project slot the request is scoped to. |
--session <id> | none | Session id tying this request to the agent run that made it. |
--exec <program> | none | Program the secret is requested for, by name on PATH or by path; makes this an exec scope. Needs --env. |
--env <VAR> | none | Environment variable the program receives the secret in. Needs --exec. |
--backend <backend> | keychain | Backend whose index is read: keychain, file or memory. |
The caller is identified the way ak secrets resolve identifies it, by
walking the parent-process chain to a recognized agent and hashing its binary;
a request from no identified agent is refused. Nothing in a secret's profile is
read to decide a request, and no grant is ever inherited from one: a request
for a scope is answered by a grant on exactly that scope.
--exec with --env asks for an exec scope: the value delivered only in that
environment variable of the program --exec names, pinned by its resolved path
and content hash, for ak secrets run. Shells,
launchers and variables that steer a loader, a runtime or a network endpoint
are refused. Repeated requests for one scope are one inbox entry, and a caller
that asks too often is refused until its cool-down passes.
The command reads the secrets index and the grant file. When no grant covers the scope, it files the request in the approval inbox and writes one row to the secrets audit ledger; a blocked scope writes a block row. It never reads or prints a value.
Output
Human stdout prints the status and ref on the first line (pending <ref> or
granted <ref>), then the agent fingerprint, project, purpose, the exec scope
when one was asked for, any warnings, and a next line saying what happens
now.
JSON success uses:
schema_version: 1
kind: secrets.request
data.ref
data.project
data.purpose
data.fingerprint
data.agentLabel?
data.exec?
data.status: pending | granted
data.warnings?[]
data.nextstatus is pending when the request is waiting for the operator and
granted when a grant already covers the scope; in both cases nothing was
released. exec is present only for an exec scope and names the resolved
program, its hash and the variable.
Exit behavior
| Exit | Meaning |
|---|---|
0 | The request is waiting for the operator, or a grant already covers it. |
2 | Invalid flags, purpose, ref, exec program or env name. |
3 | No secret by that ref. |
5 | The index, grant file, inbox or audit ledger could not be used. |
6 | A block refuses the caller, or its identity cannot be named. |
9 | The caller asked too often and is in its cool-down. |
15 | A synced vault policy refuses this release, or whether one governs it cannot be answered; the JSON error's sync.reason names why. |