Skip to main content
This walkthrough follows one action, a refund, from an agent’s request to the signed record of what happened. It uses a generic external system. For the exact request and response formats, follow the links to the reference pages, which are generated from the API specification.

​
The path of one action

  1. The agent proposes an action. It sends a Business Transaction to POST /execute with its own API key. The key limits what the agent may ask for.
  2. Parmana evaluates the policy. The policy is an ordered list of rules. The first matching rule decides. If no rule matches, the action is denied. See Policies and the decision.
  3. A person approves when the policy requires it. The approver signs one approval for one action on one resource. See Human approval.
  4. Parmana issues a signed authorization. It is single-use and valid for a short window, and it is bound to the exact request content.
  5. The gateway releases the action. The gateway verifies the authorization again before it calls the external system. It is the only path to that system.
  6. The result becomes a signed record. The Execution Trust Record holds the decision, the approval and the outcome. Anyone can verify it offline. See Verify independently.

​
Before you start

​
Send the request

Send the Business Transaction to POST /execute. The request body, every field, and every response code are on the reference page, which the API specification generates: Execute a Business Transaction. Two rules apply to every request:
  • The metadata.businessTransactionId must match the top-level businessTransactionId. Otherwise the request is refused before the policy is evaluated.
  • Every signal the policy reads must come from a real source. A placeholder value is not a signal.

​
Read the response

The response says whether the action was approved, denied or refused. It also says which rule decided it. A denial is a correct decision, not an error. Branch on the status code first, then on the code. The full list of codes is in the Error catalog.

​
Verify the record

Each action that reaches the external system produces an Execution Trust Record. Verify it without calling Parmana, using the offline verifier. The steps are in Verify independently. Pin the signing key you trust, and check that the record’s coverage is full.

​
Security notes

  • The agent holds only its own key. It never holds a connector credential.
  • The external system accepts a request only with a valid authorization. Build the connector to check it.
  • A key that appears in a log, a ticket or a chat must be rotated at once.
  • The record shows what was decided and released. It does not show that the external system did what it was asked. Verify the outcome in the external system too.

​
Next