Credentials for maker, checker, approver and agent

A Parmana deployment uses four kinds of credential. This page gives the commands for creating them, deploying them, testing them and rotating them. The examples use PowerShell and placeholder names. Replace each placeholder with your own value.

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, with `scripts/generate-api-key.ts`	a SHA-256 hash in `PARMANA_API_KEYS`
Checker	Reviews and approves policy changes	API key and a step-up key pair	the checker, with `scripts/generate-api-key.ts --generate-step-up-key`	the hash, and the step-up public key
Approver (for example a refund manager)	Signs approval for one action on one resource	Ed25519 key pair, no API key	the approver, with `scripts/generate-approver-key.ts`	the public key, added through maker checker
Agent	Sends actions to `POST /execute`	API key scoped to its capabilities	the operator, with `scripts/generate-api-key.ts --allowed-capabilities`	a hash in `PARMANA_API_KEYS`

The server never holds a raw API key, a step-up private key, or an approver private key. A key that a script prints once cannot be recovered. If it is lost, create a new one.

Each person creates their own credential on their own machine. The server refuses an approval from the same caller that proposed the change (SameActorCannotApproveOwnChangeError). It cannot tell whether two callers are two people. If one person holds both the maker and the checker credentials, that is one person with two credentials, not two-person control.

Before you start

You need Node.js 24 or later and Git. Build the packages the scripts import:

# Repository access is granted by agreement with Parmana Systems.
cd parmana
npm install
npx tsc -b

Without the build, every script fails with ERR_MODULE_NOT_FOUND. Each key script prints its secret once. Save the printed Key : value in a password manager. Keep the files the scripts write outside the repository folder.

Quick path with parmana-ops

This route uses the parmana-ops CLI for everything it can do. The raw API steps further down are the same operations, written out by hand. Use this route first. Each person does their own steps, on their own machine. Nobody generates a credential for someone else.

Set up the CLI

Build and link the CLI from the repository, once per machine:

cd <repository folder>
npx tsc -b
npm link -w @parmana/cli
parmana-ops --help

Do not install the CLI with npm install -g from a folder. That pulls the published @parmana/crypto, which may not have the key commands. Set your own caller key for each command that calls the server. Use the raw key from your own step 1, never someone else’s:

$env:PARMANA_TOKEN = "<your raw API key>"

1. Generate credentials

Who	Credential	Command
maker	API key	`parmana-ops keys generate-api-key --caller-id pavancharak --out-dir "$env:USERPROFILE\parmana-keys" --credential-holder-type USER`
checker	API key and step-up key	`parmana-ops keys generate-api-key --caller-id mamta-checker --out-dir "$env:USERPROFILE\parmana-keys" --credential-holder-type USER --generate-step-up-key`
checker	approver key pair	`parmana-ops keys generate-approver-key --approver-id mamta-checker --key-id mamta-checker-key-1 --out-dir "$env:USERPROFILE\parmana-approver"`
kill-switch probe	API key	`parmana-ops keys generate-api-key --caller-id kill-switch-probe --out-dir "$env:USERPROFILE\parmana-keys" --allowed-capabilities kill-switch:probe`
kill-switch trip	API key	`parmana-ops keys generate-api-key --caller-id kill-switch-trip --out-dir "$env:USERPROFILE\parmana-keys" --allowed-capabilities kill-switch:trip`
kill-switch reset	API key, for a person	`parmana-ops keys generate-api-key --caller-id kill-switch-reset --out-dir "$env:USERPROFILE\parmana-keys" --allowed-capabilities kill-switch:reset --credential-holder-type USER`

Create trip and reset keys only when someone needs them. A reset needs a second, different operator to complete it. Each command writes owner-only files and prints paths, never secret values:

File	Secret	Keep it	Send to the operator
`<caller>.key`	yes	a password manager, then delete the file	no
`<caller>.entry.json`	no	with the operator	yes
`<caller>.step-up.private.pem`	yes	with the checker only	no
`<approver>__<key>.private.pem`	yes	with the approver only	no
`<approver>__<key>.public.pem`	no	with the approver	yes

2. Put the entries on the server

The operator merges every *.entry.json into one JSON array and sets it as PARMANA_API_KEYS in the host’s secret store, then redeploys. The entries hold only hashes, so the server cannot recover a raw key. A new value takes effect only after a redeploy.

3. Validate before you use a key

Check each credential once it is live:

$env:KEY = "<raw API key>"
curl.exe -s -H "Authorization: Bearer $env:KEY" https://your-parmana-server/callers/me

Expected: a 200 response whose callerId matches. A 401 means the key is not in the deployed list, or the deploy did not pick it up. Repeat with a retired key, which must return 401. For the kill-switch probe key, check the status route, then send one probe:

curl.exe -s -H "Authorization: Bearer $env:KEY" https://your-parmana-server/kill-switch/status
'{"status":200}' | Set-Content probe.json -Encoding ascii
curl.exe -s -X POST -H "Authorization: Bearer $env:KEY" -H "Content-Type: application/json" -d "@probe.json" https://your-parmana-server/kill-switch/probes
Remove-Item probe.json

Expected: 200 for status and 201 for the probe. The probe writes one record to the database, so send it once. A probe key without kill-switch:probe gets 403 with CAPABILITY_NOT_ALLOWED. For an approver’s public key, the first line must be the public header:

Get-Content "$env:USERPROFILE\parmana-approver\mamta-checker__mamta-checker-key-1.public.pem" -First 1

It must read -----BEGIN PUBLIC KEY-----. A PRIVATE KEY header means the wrong file was sent. Stop, and treat that private key as exposed.

4. Register an approver: maker and checker

The maker proposes the public key. A different checker approves it with a step-up signature. The change takes effect for the next request. Maker, dry run first, then the real command:

parmana-ops approver propose-add --approver mamta-checker --key mamta-checker-key-1 --public-key-file mamta-checker__mamta-checker-key-1.public.pem --capabilities razorpay:refund --reason "<the business reason>" --dry-run
parmana-ops approver propose-add --approver mamta-checker --key mamta-checker-key-1 --public-key-file mamta-checker__mamta-checker-key-1.public.pem --capabilities razorpay:refund --reason "<the business reason>"

Checker finds the change, then signs and submits it within 120 seconds:

parmana-ops approver list --status PENDING_APPROVAL
parmana-ops approval sign --key-file "$env:USERPROFILE\parmana-checker\mamta-checker.step-up.private.pem" --key-id mamta-checker --pending <change-id> --action approve --out envelope.json
parmana-ops approver submit --change <change-id> --action approve --envelope envelope.json --dry-run
parmana-ops approver submit --change <change-id> --action approve --envelope envelope.json

Check the result:

parmana-ops approver list --status APPROVED

Rules that matter:

The maker and the checker must be different callers. The server refuses an approval from the proposer.
The checker signs with the step-up key, not the approver key.
The envelope is valid for 120 seconds and works once. If it expires, sign again.

To revoke an approver, the maker proposes parmana-ops approver propose-revoke --approver <id> --key <key-id> --reason "<why>", and the checker approves it as above.

Raw API steps

The steps below do the same work by hand with PowerShell and the API. Use them when the CLI is not available.

1. Maker key

$id = "maker-example"
$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

--credential-holder-type USER is required. Policy governance endpoints accept only callers provisioned as human. A key without it is refused with NON_HUMAN_CALLER_DENIED.

2. Checker key

The checker runs this on their own machine:

$id = "checker-example"
$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 = 0..($out.Count - 1) | Where-Object { $out[$_] -like '*BEGIN*PRIVATE KEY*' } | Select-Object -First 1
$end = 0..($out.Count - 1) | Where-Object { $out[$_] -like '*END*PRIVATE KEY*' } | Select-Object -First 1
$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
`checker-example.json`	no	give it to the operator, who adds it to the deployed list

3. Approver key pair

The approver runs this on their own machine:

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

The script writes two files and refuses to overwrite existing ones. Keep the .private.pem file on the approver’s machine. Send the .public.pem file to the operator, who registers it in step 8.

4. Agent key

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

$id = "example-agent"
$out = npx tsx scripts/generate-api-key.ts --caller-id $id --allowed-capabilities erp:invoice-pay
$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

Put the key in the agent’s own configuration. Without --allowed-principal-ids, the agent may act only as itself: the principalId in its requests must equal its caller id.

5. Deploy the key list

PARMANA_API_KEYS is a JSON array with one entry per caller. Build it from the entry files, then set it in your host’s secret store and redeploy. Environment changes take effect only in a new deployment.

$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 ",") }
$value = ConvertTo-Json -InputObject $entries -Depth 5 -Compress

Set the value in your host, as PARMANA_API_KEYS, marked as a secret. Then redeploy. A caller that is not in the list loses access at that redeploy. That is how a key is revoked. Keep the entry files. A secret value cannot be read back from most hosts, so these files are the only copy of the list. If the server does not start, check the value first. PARMANA_API_KEYS is not valid JSON or must be a JSON array means the value was not saved as one array.

6. Test a key

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

$url = "https://your-parmana-server"
$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 list: 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. Change a policy: maker and checker

Propose (maker)

The body holds a reason and the whole policy.json. Its policyId must match the name in the path. Propose a new version folder. An approved version is never edited.

$url = "https://your-parmana-server"
$name = "example-policy"; $version = "1.1.0"
$sec = Read-Host -AsSecureString "Maker API key"
$key = [System.Net.NetworkCredential]::new("", $sec).Password
$policy = [System.IO.File]::ReadAllText("$PWD\policies\$name\$version\policy.json", [System.Text.Encoding]::UTF8)
$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. Give it to the checker.

Review (checker)

$url = "https://your-parmana-server"
$changeId = "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, warning and conflict before approving. Rules are evaluated first match wins. An overlap between two rules with the same outcome is harmless. An overlap between an approve rule and a reject rule decides behavior by their order.

Approve (checker)

The step-up signature is valid for 120 seconds, so run this whole block at once:

$url = "https://your-parmana-server"
$changeId = "PENDING-POLICY-CHANGE-ID"
$id = "checker-example"
$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

A successful approval shows status : APPROVED. The server verifies the signature against the step-up public key in the approving caller’s own entry. The approved version is then in effect for its action.

8. Register an approver

The recommended route is maker checker. The maker proposes the approver’s public key, and the checker approves it with a step-up signature. The change applies to the next request. See Manage approvers for the commands in curl, TypeScript and Python.

$url = "https://your-parmana-server"
$approverId = "approver-example"; $keyId = "approver-example-key-1"
$pub = "$env:USERPROFILE\parmana-approver\${approverId}__${keyId}.public.pem"
$key = [System.Net.NetworkCredential]::new("", (Read-Host "Maker API key" -AsSecureString)).Password.Trim()
$body = @{ action = "add"; approverId = $approverId; keyId = $keyId; publicKeyPem = [System.IO.File]::ReadAllText($pub); reason = "New approver key" } | ConvertTo-Json -Compress
$change = Invoke-RestMethod -Method Post -Uri "$url/approval-issuers/changes" -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$change.changeId
Remove-Variable key

The checker then approves the change with the same step-up procedure as in step 7. Alternatively, a deployment can list approvers in code. Add the entry to TRUSTED_APPROVAL_ISSUERS in packages/api/src/bootstrap/codeApprovalIssuers.ts through a pull request. Merging deploys it. Until an approver is listed, every signed approval from that approver is refused.

9. Sign one approval

An approver signs one action on one resource, up to an amount. The default validity is 15 minutes, and the approval can be used once:

$id = "approver-example"
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 erp:invoice-pay --resource-id INV-1042 --max-amount 75000 --out approval

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

To	Do
rotate an API key	run its step 1, 2 or 4 again, which overwrites its entry file, then step 5
revoke a caller	delete its entry file, then step 5
rotate a checker’s step-up key	step 2 again on the checker’s machine, then step 5
rotate an approver key	register a new key id (step 8), then revoke the old one
revoke an approver registered through maker checker	propose a revoke change to `/approval-issuers/changes` and approve it (Manage approvers)
revoke an approver listed in code	set `revoked: true` in `TRUSTED_APPROVAL_ISSUERS`, then deploy

Rotate a key at once if it was pasted into a chat, a ticket or a log. When a service holds several values from Parmana, change them together, or requests fail between the changes. Set all of them, then redeploy both sides. A new value takes effect only in a new deployment. Afterwards, GET /callers/me with the new key should return its caller id.

Troubleshooting

Symptom	Cause	Fix
`ERR_MODULE_NOT_FOUND`	the repository is not built	run `npx tsc -b`
`authentication required`	the key is not in the deployed list	check step 6, then redeploy after changing the list
`NON_HUMAN_CALLER_DENIED`	the entry lacks `credentialHolderType: USER`	create the key again with `--credential-holder-type USER`
an approval is refused as the proposer	the maker and the checker are the same caller	approve with a different caller
step-up refused	signed more than 120 seconds before it was sent, or the wrong private key	sign and send in one block
`publicKeyPem must be an Ed25519 public key`	the file was read in a form that changes its text	read the file as UTF-8 text, as in step 8
`PARMANA_API_KEYS is not valid JSON`	the value was not saved as one JSON array	rebuild the value from the entry files and set it again
`Refusing to overwrite an existing file`	a key file with that name already exists in the output folder	choose another `--out-dir`, or move the old file aside; the old key is not replaced
`--caller-id must use only letters, digits, ".", "_" and "-"`	the ID would not be a safe file name	use a simpler ID, for example `mamta-checker`
`--generate-step-up-key requires --credential-holder-type USER`	a step-up key was requested for a non-human caller	add `--credential-holder-type USER`
`is a public key. Sign with the private key`	`approval sign --key-file` was given the public PEM	pass the step-up private PEM instead
`is not a readable private key in PEM format`	the key file is damaged or not PEM	regenerate the key pair; do not repair the file by hand
`--reason is required to reject`	`approver submit --action reject` without a reason	add `--reason "<why>"`
`CAPABILITY_NOT_ALLOWED` (403)	the key lacks the capability, or has no `allowedCapabilities`	add the capability to the key’s entry and redeploy
`SameActorCannotApproveOwnChangeError`	the checker used the maker’s key	approve with the checker’s own key
`PARMANA_TOKEN` not set or rejected (401)	the token is missing, or it is not in the deployed list	set `$env:PARMANA_TOKEN` to your own raw key, then check it with `GET /callers/me`
envelope expired or already used	the step-up signature is older than 120 seconds, or it was submitted before	sign again and submit within 120 seconds
the kill-switch probe returns 403	the probe key is not the `kill-switch-probe` entry, or lacks `kill-switch:probe`	check the entry’s `allowedCapabilities` and redeploy

Command-line tools

Build with Parmana

Verify and audit

Worked examples

Credentials for maker, checker, approver and agent

The four credentials

Before you start

Quick path with parmana-ops

Set up the CLI

1. Generate credentials

2. Put the entries on the server

3. Validate before you use a key

4. Register an approver: maker and checker

Raw API steps

1. Maker key

2. Checker key

3. Approver key pair

4. Agent key

5. Deploy the key list

6. Test a key

7. Change a policy: maker and checker

Propose (maker)

Review (checker)

Approve (checker)

8. Register an approver

9. Sign one approval

10. Rotate or revoke

Troubleshooting

​The four credentials

​Before you start

​Quick path with parmana-ops

​Set up the CLI

​1. Generate credentials

​2. Put the entries on the server

​3. Validate before you use a key

​4. Register an approver: maker and checker

​Raw API steps

​1. Maker key

​2. Checker key

​3. Approver key pair

​4. Agent key

​5. Deploy the key list

​6. Test a key

​7. Change a policy: maker and checker

​Propose (maker)

​Review (checker)

​Approve (checker)

​8. Register an approver

​9. Sign one approval

​10. Rotate or revoke

​Troubleshooting

The four credentials

Before you start

Quick path with parmana-ops

Set up the CLI

1. Generate credentials

2. Put the entries on the server

3. Validate before you use a key

4. Register an approver: maker and checker

Raw API steps

1. Maker key

2. Checker key

3. Approver key pair

4. Agent key

5. Deploy the key list

6. Test a key

7. Change a policy: maker and checker

Propose (maker)

Review (checker)

Approve (checker)

8. Register an approver

9. Sign one approval

10. Rotate or revoke

Troubleshooting