Credentials for maker, checker, approver and agent

A running Parmana deployment needs four kinds of credential. This page gives every command, in Windows PowerShell, from creating the keys to approving a policy and signing a refund approval. Every command here was checked against the scripts and routes it names.

The four credentials

Role	What it does	Credential	Created by	Where the server keeps it
Maker	Proposes policy changes	API key (a human caller)	the maker, `scripts/generate-api-key.ts`	a SHA256 hash in `PARMANA_API_KEYS`
Checker	Reviews and approves policy changes	API key and a step up key pair	the checker, `scripts/generate-api-key.ts --generate-step-up-key`	the hash and the step up public key in `PARMANA_API_KEYS`
Approver (for example a refund manager)	Signs approval for one action, such as a refund above 10000	Ed25519 key pair, no API key	the approver, `scripts/generate-approver-key.ts`	the public key in `TRUSTED_APPROVAL_ISSUERS` (code)
Agent	Sends actions to `POST /execute`	API key scoped to its capabilities	the operator, `scripts/generate-api-key.ts --allowed-capabilities`	a hash in `PARMANA_API_KEYS`

What the server never holds: a raw API key, a step up private key, or an approver private key. A key shown once by a script cannot be recovered; if it is lost, you make a new one.

Each person creates their own credential on their own machine. If one person creates the checker or approver key for someone else, that person holds both halves of maker and checker. The server checks that the approving caller differs from the proposing caller (SameActorCannotApproveOwnChangeError). It cannot tell whether two callers are two people. If one person holds both, say so: it is one person with two credentials, not two person control.

Before you start (every machine, once)

You need Node.js 24 or later and Git.

git clone https://github.com/pavancharak/AgentLabsBuildathon.git
cd AgentLabsBuildathon
npm install
npx tsc -b

npx tsc -b builds the packages the scripts import. Without it every script fails with ERR_MODULE_NOT_FOUND ... @parmana\shared\dist\index.js. Each key script prints its secret once. The blocks below save everything to files automatically, so only the printed Key : value needs to go into a password manager. Keep the files outside the repository folder: the repository is public.

foreach ($d in "parmana-entries", "parmana-checker", "parmana-approver") {
  New-Item -ItemType Directory -Force "$env:USERPROFILE\$d" | Out-Null
}

parmana-entries holds one JSON line per caller: the caller id, the key hash and, for a checker, the step up public key. None of it is secret. It is what you deploy.

1. Maker key (the maker runs this)

Replace maker-NAME with the maker’s caller id.

$id = "maker-NAME"
$out = npx tsx scripts/generate-api-key.ts --caller-id $id --credential-holder-type USER
$out | Where-Object { $_ -match '^(Caller ID|Key)\s+:' }
$out | Where-Object { $_.StartsWith('{"callerId"') } | Set-Content "$env:USERPROFILE\parmana-entries\$id.json" -Encoding ascii
Remove-Variable out

Save the printed Key : value in a password manager now. --credential-holder-type USER is required: policy governance endpoints accept only callers provisioned as human (packages/api/src/auth/isHumanCaller.ts), and a key without it is refused with NON_HUMAN_CALLER_DENIED.

2. Checker key (the checker runs this, on their own machine)

$id = "reviewer-NAME"
$out = npx tsx scripts/generate-api-key.ts --caller-id $id --credential-holder-type USER --generate-step-up-key
$out | Where-Object { $_ -match '^(Caller ID|Key)\s+:' }
$start = [array]::IndexOf($out, '-----BEGIN PRIVATE KEY-----')
$end = [array]::IndexOf($out, '-----END PRIVATE KEY-----')
$out[$start..$end] | Set-Content "$env:USERPROFILE\parmana-checker\step-up.private.pem" -Encoding ascii
$out | Where-Object { $_.StartsWith('{"callerId"') } | Set-Content "$env:USERPROFILE\parmana-checker\$id.json" -Encoding ascii
Remove-Variable out

Output	Secret	What to do
`Key :` value	yes	the checker’s password manager
`step-up.private.pem`	yes	stays on the checker’s machine; it signs every approval
`reviewer-NAME.json`	no	send it to the operator, who puts it in their `parmana-entries` folder

3. Approver key pair (the approver runs this, on their own machine)

$id = "manager-NAME"
npx tsx scripts/generate-approver-key.ts --approver-id $id --key-id "$id-key-1" --out-dir "$env:USERPROFILE\parmana-approver"

It writes two files, and refuses to overwrite existing ones:

File	Secret	What to do
`manager-NAME__manager-NAME-key-1.private.pem`	yes	stays on the approver’s machine
`manager-NAME__manager-NAME-key-1.public.pem`	no	send it to the operator (step 8)

4. Agent key (the operator runs this)

Grant only the capabilities the agent needs. For a refund agent:

$id = "paytm-refund-agent"
$out = npx tsx scripts/generate-api-key.ts --caller-id $id --allowed-capabilities paytm:refund
$out | Where-Object { $_ -match '^(Caller ID|Key)\s+:' }
$out | Where-Object { $_.StartsWith('{"callerId"') } | Set-Content "$env:USERPROFILE\parmana-entries\$id.json" -Encoding ascii
Remove-Variable out

The key goes into the agent’s own configuration. With no --allowed-principal-ids, the agent may only act as itself: the principalId in its requests must equal its caller id.

5. Deploy the API keys (the operator runs this)

PARMANA_API_KEYS is a JSON array of the entries. This block builds it from every file in parmana-entries, replaces the variable on Vercel and redeploys, because an environment change only takes effect in a new deployment. The first time, it links a folder to the Vercel project (run vercel login before).

$link = "$env:USERPROFILE\parmana-vercel-link"
if (-not (Test-Path "$link\.vercel")) {
  New-Item -ItemType Directory -Force $link | Out-Null
  vercel link --yes --project parmana-api-real --scope YOUR-VERCEL-SCOPE --cwd $link
  Remove-Item "$link\.env.local" -ErrorAction SilentlyContinue
}
$entries = @(Get-ChildItem "$env:USERPROFILE\parmana-entries\*.json" | ForEach-Object { Get-Content $_.FullName -Raw | ConvertFrom-Json })
$entries | ForEach-Object { "{0}  human={1}  stepUp={2}  capabilities={3}" -f $_.callerId, ($_.credentialHolderType -eq "USER"), ($null -ne $_.stepUpPublicKey), ($_.allowedCapabilities -join ",") }
Read-Host "Only these callers will work in production. Enter to continue, Ctrl+C to stop"
$value = ConvertTo-Json -InputObject $entries -Depth 5 -Compress
vercel env rm PARMANA_API_KEYS production --yes --cwd $link
$value | vercel env add PARMANA_API_KEYS production --sensitive --cwd $link
$latest = vercel ls parmana-api-real --prod --cwd $link 2>$null | Select-Object -First 1
vercel redeploy $latest --target production --cwd $link

Every caller not in the folder loses access at that redeploy. That is how a key is revoked. Keep the parmana-entries folder: a sensitive Vercel variable cannot be read back, so this folder is the only copy of the list. Do not use scripts/rotate-caller-key.mjs for this. It rewrites an entry as only a caller id and a hash, dropping credentialHolderType and stepUpPublicKey, so a human caller would lose access to policy governance.

6. Test a key

GET /callers/me returns the caller id of a key, and never the key itself.

$url = "https://parmana-api-real.vercel.app"
$sec = Read-Host -AsSecureString "API key"
$key = [System.Net.NetworkCredential]::new("", $sec).Password
$h = @{ Authorization = "Bearer $key" }
try { (Invoke-RestMethod -Uri "$url/callers/me" -Headers $h).callerId } catch { $_.ErrorDetails.Message }
Remove-Variable key, sec, h

Response	Meaning
the caller id	the key works
`authentication required`	the key is not in the deployed `PARMANA_API_KEYS` (wrong key, lost key, or not redeployed)
`NON_HUMAN_CALLER_DENIED` on a governance endpoint	the key works but its entry lacks `credentialHolderType: USER`

7. Maker and checker: change a policy

Propose (maker)

The body needs reason and proposedContent, the whole policy.json, whose policyId must match the name in the path.

$url = "https://parmana-api-real.vercel.app"
$name = "customer-refund"; $version = "1.1.0"
$sec = Read-Host -AsSecureString "Maker API key"
$key = [System.Net.NetworkCredential]::new("", $sec).Password
$policy = Get-Content "policies\$name\$version\policy.json" -Raw
$body = [System.Text.Encoding]::UTF8.GetBytes("{`"reason`":`"Why this change is needed`",`"proposedContent`":$policy}")
Invoke-RestMethod -Method Post -Uri "$url/policies/$name/$version/pending-changes" -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body $body
Remove-Variable key, sec

The response holds pendingPolicyChangeId. Send it to the checker.

Review (checker)

$url = "https://parmana-api-real.vercel.app"
$changeId = "THE-PENDING-POLICY-CHANGE-ID"
$sec = Read-Host -AsSecureString "Checker API key"
$key = [System.Net.NetworkCredential]::new("", $sec).Password
$r = Invoke-RestMethod -Uri "$url/policies/pending-changes" -Headers @{ Authorization = "Bearer $key" }
$c = $r.changes | Where-Object { $_.pendingPolicyChangeId -eq $changeId }
$c | Select-Object policyName, policyVersion, status, proposedBy, reason | Format-List
foreach ($rule in $c.diff.proposed.rules) { "{0,-38} {1,-8} {2}" -f $rule.id, $rule.outcome.action, ($rule.condition | ConvertTo-Json -Depth 10 -Compress) }
"Coverage warnings: " + ($c.coverageWarnings | ConvertTo-Json -Depth 5 -Compress)
"Rule conflicts:    " + ($c.ruleConflicts | ConvertTo-Json -Depth 5 -Compress)
Remove-Variable key, sec

Read every rule, and every warning and conflict. Rules are evaluated first match wins, so an overlap between two rules with the same outcome is harmless, while an overlap between an approve rule and a reject rule decides behavior by their order. If anything is wrong, do not approve.

Approve (checker)

The step up signature is valid for 120 seconds: run the whole block at once.

$url = "https://parmana-api-real.vercel.app"
$changeId = "THE-PENDING-POLICY-CHANGE-ID"
$id = "reviewer-NAME"
$pem = "$env:USERPROFILE\parmana-checker\step-up.private.pem"
$sec = Read-Host -AsSecureString "Checker API key"
$key = [System.Net.NetworkCredential]::new("", $sec).Password
$signed = npx tsx scripts/sign-policy-change-step-up.ts --private-key-file $pem --key-id $id --pending-policy-change-id $changeId --action approve
$envelope = $signed | Where-Object { $_.StartsWith("{") } | Select-Object -First 1
$body = [System.Text.Encoding]::UTF8.GetBytes("{`"stepUpAuthorization`":$envelope}")
try {
  Invoke-RestMethod -Method Post -Uri "$url/policies/pending-changes/$changeId/approve" -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body $body
} catch { $_.ErrorDetails.Message }
Remove-Variable key, sec

The response shows status : APPROVED. The server verifies the envelope against the step up public key in the approving caller’s own entry, not against --key-id. From then on, the approved version is the one in effect for its action, with no deploy (docs/CLAIMS.md 2.43).

8. Register an approver (operator, with a pull request)

Approvers are listed in code. Add the entry with the public key file’s contents to TRUSTED_APPROVAL_ISSUERS in packages/api/src/bootstrap/createApprovalIssuerRegistry.ts:

const TRUSTED_APPROVAL_ISSUERS: readonly ConfiguredApprovalIssuer[] = [
  {
    approverId: "manager-NAME",
    keyId: "manager-NAME-key-1",
    revoked: false,
    publicKeyPem: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  },
];

Open a pull request; merging deploys it. Until an approver is listed, every signed approval is refused. To revoke an approver, set revoked: true and deploy.

9. Approver: sign one approval

For one action on one resource, up to an amount, valid 15 minutes by default, usable once:

$id = "manager-NAME"
npx tsx scripts/sign-approval.ts --private-key-file "$env:USERPROFILE\parmana-approver\${id}__${id}-key-1.private.pem" --approver-id $id --key-id "$id-key-1" --capability paytm:refund --resource-id ORD-1042 --max-amount 75000 --out approval.json

The agent sends a new request with managerApproved: true and the contents of approval.json in signals.approvalArtifact. See Human approval.

10. Rotate or revoke a key

To	Do
rotate an API key	run its step 1, 2 or 4 again (it overwrites the entry file), then step 5
revoke a caller	delete its file from `parmana-entries`, then step 5
rotate a checker’s step up key	step 2 again on the checker’s machine, then step 5
revoke an approver	`revoked: true` in `TRUSTED_APPROVAL_ISSUERS`, then deploy

Rotate at once if a key was pasted into a chat, a ticket or a log.

What was done on 2026-09-27

The production deployment was rebuilt with these steps, in this order:

The operator had no working human key, and two keys had been shown in a chat transcript. Every production API key was replaced from scratch with step 5; the old policy-maker, policy-reviewer-1 and paytm-refund-agent keys stopped working at the redeploy.
The operator decided to hold the maker, checker and approver roles for now. New callers: charak1987 (maker), reviewer-charak1987 (checker, with a step up key) and paytm-refund-agent (paytm:refund only). Governance in production is therefore one person with two credentials until a second person replaces the checker.
reviewer-charak1987 reviewed and approved customer-refund 1.1.0 (change 008f504d-0efd-4bec-b33a-2991bb84099f, proposed by policy-maker) at 18:53:40 UTC. Refunds now run under 1.1.0: automatic up to 10000, a verified manager approval above 10000 and up to 100000, refused above 100000.
The refund agent key was deployed after the approval, so no refund ran under 1.0.0 with the new key, and the refund agent’s Vercel project was given it.
A refund manager key pair, manager-charak1987, was created and, on 2026-09-28, added to TRUSTED_APPROVAL_ISSUERS (step 8). Before that, every production refund above 10000 was refused.

The record is docs/progress/2026-09-27-HUMAN-APPROVAL.md.

Troubleshooting

Symptom	Cause	Fix
`ERR_MODULE_NOT_FOUND ... @parmana\shared\dist`	the clone is not built	`npx tsc -b`
`The '<' operator is reserved for future use`	a placeholder such as `<name>` was typed literally	replace it with the real value, without angle brackets
`authentication required`	the key is not in the deployed list	check step 6; redeploy after changing the list
`NON_HUMAN_CALLER_DENIED`	the entry lacks `credentialHolderType: USER`	make the key again with `--credential-holder-type USER`
approve refused as the proposer	maker and checker are the same caller	approve with a different caller
step up refused	signed more than 120 seconds before sending, or the wrong private key	sign and send in one block
a Vercel command stops with `NativeCommandError` in a script	Windows PowerShell 5.1 treats the CLI’s banner on stderr as an error when `$ErrorActionPreference` is `Stop`	use `Continue` around Vercel commands and check the result
`ConvertFrom-Json : Invalid JSON primitive`	the clipboard held a command, not the value	read the value with `Read-Host` or from a file instead
`$*` or a missing backslash in a pasted command	the command was copied from a rendered page that mangled it	copy from the source file

Build with Parmana

Verify and audit

Worked examples

Credentials for maker, checker, approver and agent

The four credentials

Before you start (every machine, once)

1. Maker key (the maker runs this)

2. Checker key (the checker runs this, on their own machine)

3. Approver key pair (the approver runs this, on their own machine)

4. Agent key (the operator runs this)

5. Deploy the API keys (the operator runs this)

6. Test a key

7. Maker and checker: change a policy

Propose (maker)

Review (checker)

Approve (checker)

8. Register an approver (operator, with a pull request)

9. Approver: sign one approval

10. Rotate or revoke a key

What was done on 2026-09-27

Troubleshooting

​The four credentials

​Before you start (every machine, once)

​1. Maker key (the maker runs this)

​2. Checker key (the checker runs this, on their own machine)

​3. Approver key pair (the approver runs this, on their own machine)

​4. Agent key (the operator runs this)

​5. Deploy the API keys (the operator runs this)

​6. Test a key

​7. Maker and checker: change a policy

​Propose (maker)

​Review (checker)

​Approve (checker)

​8. Register an approver (operator, with a pull request)

​9. Approver: sign one approval

​10. Rotate or revoke a key

​What was done on 2026-09-27

​Troubleshooting

The four credentials

Before you start (every machine, once)

1. Maker key (the maker runs this)

2. Checker key (the checker runs this, on their own machine)

3. Approver key pair (the approver runs this, on their own machine)

4. Agent key (the operator runs this)

5. Deploy the API keys (the operator runs this)

6. Test a key

7. Maker and checker: change a policy

Propose (maker)

Review (checker)

Approve (checker)

8. Register an approver (operator, with a pull request)

9. Approver: sign one approval

10. Rotate or revoke a key

What was done on 2026-09-27

Troubleshooting