Your agent proposes an action. Humsana binds the authority to that exact action. Immediately before the action runs, your executor asks the same question again, against the parameters it is about to send, and the call proceeds only if the answer still matches. Without a valid binding, the action does not run.
Registration names the bound values, the consequence and any human step, for classes like payments.release, filing.submit, access.revoke or records.delete.
POST /v1/authorize/verify with the principal, the action and its parameters.
The principal's identity system authenticates the human. Humsana signs the approval over the digest.
POST /v1/authorize/effectuate with the receipt and the action about to run.
It carries what was authorized and presented, both digests and the policy version.
| Decision | What it means |
|---|---|
| ALLOW | The action proceeds. |
| ALLOW_WITH_LIMITS | It proceeds with the limits applied. |
| VERIFY | Something is verified first. |
| HUMAN_CONFIRM | An authenticated human approves this exact action. |
| HOLD | It waits until something changes. |
| DENY | It does not proceed. |
The grant is single use: the check that passes spends it.
Humsana checks at the seam the integrating party controls.
POST /v1/authorize/effectuate
{
"receipt_id": "rcpt_8f21c0",
"binding_digest": "sha256:9c1f...",
"final_action": { "name": "payments.release",
"parameters": { "payee_account": "GB00SUPPLIER00004821", "amount_gbp": "1800" } }
}
// 200 MATCHED
{ "code": "MATCHED",
"decision": "ALLOW",
"matched": true,
"consumed": true,
"grant_id": "grant_v2RT39_NY3B84w_oZ4OMA-s9_Y_YvM7b",
"confirmed_by": { "subject": "reviewer@northwind.example",
"adapter": "reference", "method": "hmac-sha256" } }
// 200
{ "code": "GRANT_DOES_NOT_COVER_THIS_ACTION",
"decision": "DENY",
"matched": false,
"consumed": false,
"policy_version": 1,
"drift": [ { "field": "parameters.payee_account",
"authorized": "GB00SUPPLIER00004821",
"final": "GB00SUPPLIER00009137",
"rule": "MAY_NOT_CHANGE" } ] }
| Endpoint | Purpose |
|---|---|
| POST /v1/authorize/verify | Propose an action, receive a decision and a binding. |
| POST /v1/authorize/effectuate | Present the action at execution. |
| POST /v1/authorize/confirm | Record the confirmation, bound to the digest. |
| POST /v1/authorize/challenge | Ask for the challenge. |
| POST /v1/authorize/confirm/request | Request the confirmation step. |
| GET /v1/health | The service summary: policy version, confirmation mode, and the limits a caller is held to. Send a key for the running configuration: detector, detector version, gates, queue depth. |
Bearer key authentication, except for GET /v1/health, which answers without one.
python3 -m receipt.verify record.receipt.json --key key.pub.json
The integration guide is available on request.