# Parmana: integration documentation in full > Parmana is an authorization layer between a caller (an AI agent, a script or a person) and the business systems that carry out an action. The caller sends a Business Transaction that describes the intended action. A policy engine decides. If the action is approved, Parmana signs an authorization, releases the action to the connector, and returns a signed Execution Trust Record that anyone can verify without trusting Parmana. The caller never holds the credentials for the target system. This file concatenates the integration pages of the Parmana documentation. It is generated. Do not edit it by hand. Regenerate it with `npm run generate:llms-txt`. The index of every page is at https://docs.parmanasystems.com/llms.txt. --- ## Welcome Source: https://docs.parmanasystems.com **The Institutional Authority Layer for Autonomous Systems.** AI agents can propose and start actions. Institutions decide what authority to delegate. Parmana checks each action against that authority before it runs, and keeps signed evidence that anyone can verify. **Apache License 2.0.** The whole Parmana repository, including the server, is open source under the Apache License 2.0, as are the client and connector SDKs. See [License](/license). Evaluators and auditors start with [How Parmana compares](/how-parmana-compares) and [Verify independently](/guides/verify-independently). ## Access is not authority Access controls answer one question: can this agent reach this system? That matters, but it is not the question that matters when an agent is about to issue a refund or change a record. The question is whether this specific action, for this amount and in these circumstances, is within what your institution actually delegated. Parmana answers that question before the action runs, using rules your institution writes and a person's signature where the rules require one. ## What Parmana controls 1. **Declared.** Your institution writes its authority as explicit, versioned rules: what each action may do, up to what amount, and when a person must approve it. 2. **Authorized.** Each proposed action is checked against those rules. If no rule matches, the action is refused. A rule that needs a person waits for a signed approval for that exact action. 3. **Executed.** Only permitted actions pass the enforcement boundary. On supported paths, the gateway holds the connector credentials, so the agent never does, and it releases each approved action once. 4. **Proven.** A signed record of the decision and the release, which anyone can verify offline with the public key they choose to trust. Each stage is built and tested. [How Parmana thinks](/how-parmana-thinks) sets out what each stage guarantees, and where it stops. ## An example A support agent asks to refund 4,000 to a customer. Your policy lets the agent refund up to 500 on its own. Above 500, it needs a signed approval from a named manager for that order and that amount. Parmana refuses the request, so nothing is refunded. The manager reviews it and signs an approval for that order and amount, valid for 15 minutes and usable once. The agent sends the request again. Parmana releases the refund through your refund system, and the record shows the decision, the approval and the release. ## What the institution receives - **Control.** Rules you can read, change only through a second approver, and enforce whether the caller is a person or an agent. - **Accountability.** A signed record of each decision, approval and release, tied to the action it covers. - **Independent evidence.** Records that an auditor or regulator can verify without access to your systems or to Parmana. ## What Parmana is not Parmana does not replace identity and access management, AI security tools or AI governance. Each answers a different question, and Parmana sits after them, in front of the actions an agent takes. [How Parmana compares](/how-parmana-compares) sets out the difference. ## Where Parmana stands It checks only actions that go through its gateway, and it does not read the text a model produces. Every claim, with its evidence and its limits, is recorded in the repository. **Try it on your own machine.** The [Quickstart](/quickstart) runs a local Parmana server: a policy refuses a request, you give a signed approval, the request goes through, and you verify the signed record yourself. **AI agent reading this?** `GET /api-manifest.json` on any deployment is a single machine-readable index of the OpenAPI spec, auth scheme, and both real SDKs with their actual current package versions, no page-scraping required. To start, the [Quickstart](/quickstart) gets you a working local server and a test credential (not a production secret). ## Status tags used throughout this site Built and tested in this repo today. Cites the source file(s) and/or test(s) that prove it. Exists, but incomplete. States exactly what works and what doesn't. Designed, not yet built. Says so in the first sentence, never documented as if it ships. A page or section with no tag is a bug in this site, [file it as such](/contributing). ## Where to go next Install to first authorized execution, using the in-memory server. Run Parmana on your own infrastructure with one Docker Compose command. Decisions, keys and records stay in your network. The concepts behind the four stages above: policy, authorization, the gateway, trust records. TypeScript and Python, both published, both with a builder that removes the most common integration mistake. One spec, three views: this site's per-route reference, a live Swagger UI to try requests, and a read-only ReDoc page. Content on this site is periodically verified against a specific commit; see [Changelog](/changelog) for what changed and when. --- ## Choose your path Source: https://docs.parmanasystems.com/choose-your-path Find your goal in the table. Each row names one place to start, what you need before you begin, and the first command or request. If two rows seem to apply, do the earlier one first. ## What do you want to do? | Your goal | Start here | You need | First step | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **See Parmana work right now**, with nothing installed | [Quickstart](/quickstart) | A browser, or cURL or PowerShell | `GET https://parmana-api-real.vercel.app/callers/me` with the demo key | | Put Parmana in front of an AI agent's actions, from **TypeScript** | [TypeScript SDK quickstart](/guides/typescript-sdk-quickstart) | Node 20 or later, a Parmana API URL, an API key | `npm install @parmana/sdk` | | Put Parmana in front of an AI agent's actions, from **Python** | [Python SDK quickstart](/guides/python-sdk-quickstart) | Python 3.10 or later, a Parmana API URL, an API key | `pip install parmana` | | Integrate from **any other language**, or with a plain HTTP client | [REST API introduction](/api-reference/introduction) and [Authentication](/api-reference/authentication) | Any HTTP client, a Parmana API URL, an API key | `POST /execute` with a Bearer key | | Let Parmana release approved actions to a system you already use (an external endpoint you register) | [Connectors overview](/integrations/overview) | A running Parmana server with that connector's credentials configured | Read the overview, then the connector's page | | Build a **new connector** for a system Parmana does not support yet | [Add a connector](/guides/add-a-connector) then the [Connector development guide](/integrations/connector-development-guide) | Node or Python, and the system's API credentials | `npm install @parmana/connector-sdk` or `pip install parmana-connector-sdk` | | **Run Parmana on your own infrastructure**, with its own Postgres, in one command | [Self hosted quickstart](/self-hosted/quickstart), after the [Self hosted overview](/self-hosted/overview) | Docker with Docker Compose v2, a clone of the repository | `docker compose up -d --build --wait` | | **Run Parmana from source** on your own machine, for development | [Local deployment](/deployment/local) | Node 24 or later | Follow the page top to bottom | | **Run Parmana in production** | [Production deployment](/deployment/production) and the [Environment variable reference](/deployment/environment-variables) | A host that runs Node 24 or later or a container, a Postgres database (Supabase), signing keys | Follow the page top to bottom | | Decide **what an agent is allowed to do** | [Write your first policy](/guides/write-your-first-policy) | A running Parmana server | Copy the example policy and change one rule | | **Approve or reject a change** to a policy | [Policy governance](/guides/policy-governance-maker-checker) | A human credential and a step up signing key | Read the page, then follow the approval steps | | **Check a record** someone gave you, as an auditor, without trusting Parmana | [Verify a trust record independently](/guides/verify-independently) | The record and Parmana's public key | Follow the page top to bottom | | Understand **why** Parmana works this way before you commit | [How Parmana thinks](/how-parmana-thinks) | Nothing | Read it, it is short | ## The three steps every integration does Whatever language you use, an integration is these three steps, in this order. 1. **Get a key.** Every request carries `Authorization: Bearer `. Keys are issued by whoever runs the Parmana server. See [Authentication](/api-reference/authentication). 2. **Send the action for a decision.** Describe what the agent wants to do as a Business Transaction and send it with `POST /execute`. Give it a fresh `businessTransactionId` (a UUID) every time, because that identifier is the idempotency key. See [Idempotency and nonces](/api-reference/idempotency-and-nonces). 3. **Act on the answer, and only on the answer.** Proceed only when the response is HTTP `200` and `executions[0].decision.outcome` is `APPROVED`. Treat everything else as "not authorized". The next section lists every answer. ## What each answer means, and what to do | You receive | Meaning | What to do | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` and `decision.outcome` is `APPROVED` | Policy approved it, and the action was released to the connector. You get a signed Execution Trust Record. | Proceed. Keep the record. | | `403` with code `POLICY_DENIED` | A policy rule said no. This is a final decision. | Do not proceed. Do not retry the same request. | | `403` with no code | Your key is not allowed to assert that principal. | Fix the key's permissions. | | `403` with code `CAPABILITY_NOT_ALLOWED` | Your key is not allowed to invoke that action. | Fix the key's capabilities. | | `401` | The key is missing or wrong. | Fix the key. | | `400` | The request is malformed. | Fix the request. See the [error catalog](/api-reference/error-catalog). | | `409` | That `businessTransactionId` was already used. | Do not send it again. Look up the existing record instead. | | `429` | You are rate limited. | Wait for the time in the `Retry-After` header, then retry with a new `businessTransactionId`. | | `503` with code `SIGNING_UNAVAILABLE` | Parmana could not sign evidence, so it refused **before** releasing the action. **Nothing was executed.** | Retry later with a new `businessTransactionId`. | | `503` with code `EXECUTION_INTENT_UNAVAILABLE` | Parmana could not sign and store the [Execution Intent](/concepts/execution-intents), so it refused **before** releasing the action. **Nothing was executed.** | Retry later with a new `businessTransactionId`. | | `500` with code `EXECUTION_RECORD_INCOMPLETE` | The action **was** released, but its signed record could not be produced. | **Do not resubmit under a new id.** Tell the operator. A signed [Execution Intent](/concepts/execution-intents) exists, and the operator can rebuild the record without repeating the action. | | `502` with code `EXECUTION_OUTCOME_UNKNOWN` | The action was released and the connector call failed, so it **may** have been performed. | **Do not resubmit.** Check the target system, then close the Execution Intent with resolve. | | Any other `5xx`, or no response | Parmana's answer is unknown. | Treat it as not authorized. Never treat "could not reach Parmana" as "allowed". | The full list, with the exact messages, is the [error catalog](/api-reference/error-catalog). ## Which SDK? | You use | Package | Current version | Install | | -------------------------------------- | ------------------------------------------- | --------------- | ------------------------------------------------------------- | | TypeScript or JavaScript | [`@parmana/sdk`](/sdks/typescript) on npm | 4.1.1 | `npm install @parmana/sdk` | | Python | [`parmana`](/sdks/python) on PyPI | 4.1.1 | `pip install parmana` | | Python, and you verify records offline | `parmana` with the `verify` extra | 4.1.1 | `pip install "parmana[verify]"` | | Another language | The [REST API](/api-reference/introduction) | Not applicable | Any HTTP client, see [Other languages](/sdks/other-languages) | Both SDKs never retry `POST /execute` for you. They only retry idempotent `GET` requests, so an SDK can never turn a single action into two. ## For AI agents If you are an AI agent, do not use this page to decide what to do. Follow [Integrate Parmana: specification for AI agents](/agents/integrate) exactly. It is written to be followed literally, one step at a time, with what to expect and what to do when the result is different. It also has the same answer table as above, in the order to apply it. ## Not sure yet Start with the [Quickstart](/quickstart): a local server, real requests and a signed record. Then read [How Parmana thinks](/how-parmana-thinks) and the [Quickstart](/quickstart). None of them needs an account. --- ## Start here for AI agents Source: https://docs.parmanasystems.com/agents/start-here This page is written for an AI agent that needs to act through Parmana. A person can read it too. Follow the steps in order. Each step names the call, the exact shape to send, the result to expect, and what to do if the result differs. If you are a crawler building an index: the authoritative machine-readable sources are [`/llms.txt`](/llms.txt) (an index of every page), [`/llms-full.txt`](/llms-full.txt) (the integration pages in full), and [`/openapi.bundled.yaml`](/openapi.bundled.yaml) (every endpoint, with its schema). ## 0. Know what Parmana will and will not do - Parmana decides whether an action may run, under a versioned policy. It does not run the action itself. A **connector** runs it, after Parmana releases it. - Every action needs a decision and a record. A refusal is a normal outcome, not an error to work around. - A rule that needs a person returns a refusal the first time. A person approves, and then you send the request again with the approval attached. - Do not change a refusal into an approval by setting a signal to `true`. The server checks signed approvals, and it refuses a `true` it cannot verify. ## 1. Check the server is up ```http GET /health ``` Expected: `200` with `{"status":"UP"}`. If it is not `UP`, stop. Do not send actions to a server that cannot check them. ## 2. Find out what a request must carry ```http GET /policies/in-effect?capability= Authorization: Bearer ``` Expected: `200` with `capability`, `policy` (`name`, `version`, `schemaVersion`), and `signals`: - `signals.facts`: every name you must send under `signals`. - `signals.schema`: the type of each fact. - `signals.bound`: facts that must equal a value in your intent. - `signals.approval`: the approval signals, and the path in your request that each approval must name. Send the `policy` object exactly as returned. Send one signal for every name in `signals.facts`. If you get `404` with `CAPABILITY_NOT_BOUND`, no policy governs that capability on this server. Stop. Do not invent a policy name. ## 3. Build the request Every request to `POST /execute` has this shape. Replace every UUID with a new one, and every timestamp with the current time in ISO 8601: ```json { "businessTransactionId": "", "metadata": { "businessTransactionId": "" }, "authority": { "authorityId": "", "authorityType": "SERVICE", "principalId": "", "issuedAt": "" }, "authorization": { "authorizationId": "", "authorityId": "", "purpose": "", "issuedAt": "" }, "intent": { "intentId": "", "authorizationId": "", "action": "", "target": "", "parameters": {}, "createdAt": "" }, "policy": { "name": "...", "version": "...", "schemaVersion": "..." }, "signals": { "": "", "approvalArtifact": "" } } ``` The server checks these rules, and refuses a request that breaks them: 1. `metadata.businessTransactionId` equals `businessTransactionId`. 2. `authorization.authorityId` equals `authority.authorityId`. 3. `intent.authorizationId` equals `authorization.authorizationId`. 4. `policy.name`, `policy.version` and `intent.action` are not empty. 5. Every `businessTransactionId` is a valid UUID. 6. A signal bound to an intent value must equal that value exactly. A mismatch is refused as `POLICY_DENIED`, with a message saying the declared signals do not match the executed intent. ## 4. Send it ```http POST /execute Authorization: Bearer Content-Type: application/json ``` Read the response, and branch on it: | Response | Meaning | Your next step | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `200`, `executions[0].decision.outcome` is `APPROVED` | Approved, released, and recorded. | Go to step 6. | | `403`, `POLICY_DENIED`, one approval signal sent as `false`, every other signal true | A person's signed approval is needed. Nothing ran. | Go to step 5. | | `403`, `POLICY_DENIED`, the message says a newer policy version took effect | The policy changed after step 2. Nothing ran. | Go back to step 2 and rebuild. | | `403`, `POLICY_DENIED`, any other reason | A rule refused. Final. | Do not retry. Report the refusal. | | `403`, `CAPABILITY_NOT_ALLOWED` | Your key may not invoke this action. | Stop. Ask the operator to grant it. | | `400` | The request is malformed. The message names the problem. | Fix it, and use a new `businessTransactionId`. | | `401` | The key is missing or wrong. | Stop. Ask for a valid key. | | `404` | The policy was not found. | Go back to step 2. | | `409` | This `businessTransactionId` was already used. | Do not resend. Go to step 7 to look it up. | | `429` | Rate limited. Nothing was recorded. | Wait the seconds in `Retry-After`, then send again with a new `businessTransactionId`. | | `503` with `SIGNING_UNAVAILABLE`, `EXECUTION_INTENT_UNAVAILABLE` or `AUDIT_UNAVAILABLE` | Refused before release. Nothing ran. | Wait, then retry with a new `businessTransactionId`. | | `500` with `EXECUTION_RECORD_INCOMPLETE` | The action ran, but its record could not be produced. | Do not resend under any id. Go to step 7 and tell the operator. | | `502` with `EXECUTION_OUTCOME_UNKNOWN` | The action was released and the connector call failed. It may have run. | Do not resend under any id. Go to step 7 and tell the operator. | | Any other `5xx`, a timeout, or no response | Unknown. | Do not proceed. Go to step 7. | ## 5. If a person must approve A refusal for want of an approval is not a failure. Parmana does not hold your request open. Do this: 1. Tell the operator what needs approving: the action, the target, and any amount. 2. Wait for a signed approval artifact from a trusted approval issuer. Do not create one yourself. 3. When you hold the artifact, send the request again, with a **new** `businessTransactionId`, the approval signal set to `true`, and the artifact exactly as received in `signals.approvalArtifact`. An approval names one action, one target and an expiry, and it can be used once. If it expires, ask for another. ## 6. Keep the record A release returns a signed Execution Trust Record. Store it. It is the evidence that the action was allowed, and it can be checked later with the public key from `GET /keys/default` and the [offline verifier](/verification/offline-verifier). ## 7. When something is unclear - Read the status table in step 4, and the [troubleshooting](/troubleshooting) page. - To look up a transaction, use `GET /execution-intents/`. If it is not found, the server did not record it. - If the outcome is `EXECUTION_OUTCOME_UNKNOWN` or `EXECUTION_RECORD_INCOMPLETE`, do not retry. Tell the operator the `businessTransactionId` and the `authorizationId` from the response. ## 8. Connecting a new external system If the capability you need is not served by Parmana's built-in connectors, an operator can register it. Registration is a change that one person proposes and a different person approves. Read [connect any external system](/guides/connect-any-external-system) and [the parmana-connect service](/connectors/parmana-connect), which is the ready-made connector service that verifies releases and runs the call. Read [why Parmana is built this way](/why-parmana-is-built-this-way) before you ask for one. ## Try it first, without a real system The [quickstart](/quickstart) runs this whole path against a Parmana server you run. Use it to confirm your request shape before you send anything real. --- ## Integrate Parmana: specification for AI agents Source: https://docs.parmanasystems.com/agents/integrate This page is written to be followed literally by an AI agent or a person. It contains no options to weigh and no background to interpret. If your situation is not covered, **stop and ask the operator**. Do not guess. ## Rules that apply to every step 1. Do the steps in order. Do not skip one. 2. At each step, compare what you received with **Expect**. If it differs, follow **If not** and stop. 3. Never invent a value. Every input in the next section comes from the operator or from a response. 4. Never send an action to Parmana and then perform it yourself. Parmana releases approved actions to the connector. You only act on the answer. 5. Treat anything not explicitly approved as **not authorized**. ## Inputs you need before you start | Input | Where it comes from | How to check it | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `PARMANA_ENDPOINT` | The operator. The base URL of the Parmana server, without a trailing slash. | It must start with `https://`, except for a local server, which uses `http://localhost:3000`. | | `PARMANA_API_KEY` | The operator. A secret string issued for you. | It is non empty. Never print it, log it or put it in a URL. | | `APPROVAL_SIGNALS` | Step 3: the keys of `signals.approval` in the server's answer. The table in [Every action needs a signed approval](#every-action-needs-a-signed-approval) shows them for the connector actions. | It is never empty. Every action needs one, reads included. If the operator says none, stop: that is not possible on a current server. | | `ACTION` | The operator. The capability name, for example `erp:invoice-pay`. | Step 2 checks your key may use it. | **No server yet? Run one on your own machine.** Follow the [Quickstart](/quickstart). Every step below works the same way against it. Do not ask for a policy version. Step 3 reads the version in effect from the server, because an approved new version replaces the old one at once and a request naming an old version is refused. ## Every action needs a signed approval No action is authorized without a signed approval from a trusted person, for that action and that resource. This holds for reads as well as writes, and for every policy: a server refuses to load a policy that could approve without one. So plan for it from the start: **your first request for an action on a new resource will be refused** until a person signs an approval for it. For the actions with a connector, the approval signal and the resource it names are: | `ACTION` | Policy in effect (step 3 confirms) | Approval signal | Resource the approval names | Other signals the policy reads | | -------------------------------- | ---------------------------------- | ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `erp:invoice-pay` | `customer-refund` 1.2.0 | `managerApproved` | `intent.parameters.orderId`, up to `intent.parameters.amount` | `refundEligible`, `fraudCheckPassed`, `refundAmount` (equal to `intent.parameters.amount`) | | `github:pr-merge` | `github-pr-approval` 1.1.0 | `mergeApproved` | `intent.target` | `branchProtected`, `repositoryAuthorized`, `requiredReviewsCompleted`, `riskScore`, `statusChecksPassed` | | `github:pr-fetch` | `github-pr-read` 1.1.0 | `readApproved` | `intent.target` | none | | `sandbox:receipt` (sandbox only) | `sandbox-receipt` 1.0.0 | `receiptApproved` | `intent.target` | none; `note` equal to `intent.parameters.note`, at most 200 characters | For any action, including one not in this table (such as an action an operator registered as an external connector, see [Connect any external system](/guides/connect-any-external-system)), step 3 returns the same information from the server: `signals.approval` names the approval signal and where its resource (and amount) are in the request. Use the server's answer over this table if they ever differ. An approval covers the action and the resource, and the amount where the table names one. It does not fix other parameters: an approval for a message does not fix the message text, and an approval for a record update does not fix the new values. Every request below carries this header: `Authorization: Bearer `. ## Step 1: check the server is reachable and safe **Do:** send `GET {PARMANA_ENDPOINT}/health`, then `GET {PARMANA_ENDPOINT}/ready`. Neither needs the header. **Expect:** 1. `/health` returns HTTP `200` and `{"status":"UP"}`. 2. `/ready` returns HTTP `200` and a body with `"status":"READY"` and `"authDisabled":false`. **If not:** 1. `/health` fails or returns anything else: stop. The server is not reachable. Tell the operator. 2. `/ready` returns HTTP `503` (`"status":"NOT_READY"`): stop. Its storage is not reachable. Tell the operator. 3. `/ready` shows `"authDisabled":true`: **stop and do not send any real action.** That server accepts requests from anyone. Tell the operator that authentication is switched off. ## Step 2: check what your key may do **Do:** send `GET {PARMANA_ENDPOINT}/callers/me` with the header. **Expect:** HTTP `200` and a body like this: ```json { "callerId": "my-agent", "allowedPrincipalIds": ["my-agent"], "allowedCapabilities": ["erp:invoice-pay"], "unrestrictedCapabilities": false } ``` Keep `callerId`. Your `authority.principalId` in step 4 must be one of `allowedPrincipalIds`, and the safe choice is `callerId`. Your `ACTION` must be in `allowedCapabilities`, or `unrestrictedCapabilities` must be `true`. **If not:** 1. HTTP `401`: the key is missing or wrong. Stop. Ask the operator for a valid key. 2. `allowedCapabilities` is empty and `unrestrictedCapabilities` is `false`: your key may invoke **nothing**. Stop. Ask the operator to grant the capability. 3. `ACTION` is not in `allowedCapabilities`: stop. Ask the operator to grant it. Do not use a different action. ## Step 3: find the policy in effect **Do:** send `GET {PARMANA_ENDPOINT}/policies/in-effect?capability=` with the header. **Expect:** HTTP `200` and a body like: ```json { "capability": "erp:invoice-pay", "policy": { "name": "customer-refund", "version": "1.2.0", "schemaVersion": "1.0.0" }, "description": "Authorizes customer refunds. Every refund above 0 and up to 100000 needs a signed manager approval for that order, covering that amount....", "signals": { "facts": [ "fraudCheckPassed", "managerApproved", "refundAmount", "refundEligible" ], "schema": { "refundEligible": "boolean", "managerApproved": "boolean", "fraudCheckPassed": "boolean", "refundAmount": "number" }, "bound": { "refundAmount": "parameters.amount" }, "approval": { "managerApproved": { "resourceId": "parameters.orderId", "value": "parameters.amount" } } } } ``` Use it like this in step 4: | Field in the answer | What you do with it | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `policy` | Send it, exactly as returned, as the request's `policy`. | | `signals.facts` | Send one entry in `signals` for **every** name in this list, with the type `signals.schema` gives it. A condition on a missing fact is always false, so leaving one out never helps. | | `signals.bound` | For each entry, the signal must equal the value at that path of your `intent` (for example `signals.refundAmount` equal to `intent.parameters.amount`). Set both from the same variable. | | `signals.approval` | Each key is an approval signal. Send it `false` until you hold a signed approval; with one, send it `true` and put the approval in `signals.approvalArtifact`. `resourceId` (and `value`) say where in your request the resource (and amount) the approval must name are: `target` means `intent.target`, `parameters.x` means `intent.parameters.x`. | | `description` | For people. Do not parse it. | The answer never contains the policy's rule conditions. The `description` is the author's text for people and may mention a limit; the server decides with the rules, not the text. Look it up again before every request: it changes when a new version is approved, with no notice to you. **If not:** HTTP `403` with code `CAPABILITY_NOT_ALLOWED` means your key may not use this action: stop and ask the operator. HTTP `404` with code `CAPABILITY_NOT_BOUND` means no policy governs this action on this server: stop and ask the operator. HTTP `409` with code `NO_APPROVED_POLICY_VERSION` or `503` with code `POLICY_VERSION_UNAVAILABLE` means every request for this action is refused right now: stop and tell the operator. Do not guess a policy. With an SDK: `client.policyInEffect(ACTION)` in TypeScript, `client.policy_in_effect(ACTION)` in Python. Both return this answer; the Python fields are `policy.schema_version` and `signals.facts`, and signal names keep their exact spelling. ## Step 4: build the Business Transaction A Business Transaction is one JSON object. Every field below is required unless it says otherwise. | Field | Type and rule | Who sets it | | ------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------- | | `businessTransactionId` | A new UUID, generated by you, **different for every request**. It is the idempotency key. | You | | `metadata.businessTransactionId` | The same UUID as above. | You | | `metadata.correlationId`, `metadata.sourceSystem` | Optional strings for your own tracing. | You | | `metadata.submittedBy` | Ignored if you send it. The server sets it from your key. | The server | | `authority.authorityId` | A new UUID. | You | | `authority.authorityType` | Exactly one of `USER`, `ROLE`, `SERVICE`, `ORGANIZATION`. Use `SERVICE` for an agent. | You | | `authority.principalId` | Must be your `callerId`, or another value in `allowedPrincipalIds`. | You | | `authority.issuedAt` | The current time as an ISO 8601 date time, for example `2026-09-20T10:00:00.000Z`. | You | | `authorization.authorizationId` | A new UUID. | You | | `authorization.authorityId` | **Equal to** `authority.authorityId`. | You | | `authorization.purpose` | A short sentence stating why the action is being requested. | You | | `authorization.issuedAt` | The current time, ISO 8601. | You | | `intent.intentId` | A new UUID. | You | | `intent.authorizationId` | **Equal to** `authorization.authorizationId`. | You | | `intent.action` | Your `ACTION`, exactly as in step 2. | You | | `intent.target` | The thing the action applies to, for example an order id. | You | | `intent.parameters` | An object with the action's parameters, for example `{"amount": 5}`. | You | | `intent.createdAt` | The current time, ISO 8601. | You | | `policy.name`, `policy.version` | The `policy` object from step 3, exactly as returned (`name`, `version`, `schemaVersion`). | You | | `policy.schemaVersion` | From step 3, with the name and version. | You | | `signals` | An object with one entry for every name in step 3's `signals.facts`. | You | | `status`, `createdAt` | Ignored if you send them. | The server | ### The consistency rules The server rejects a request that breaks rules 1 to 5 with HTTP `400` and a message that names the rule. A request that breaks rule 6 is treated as a policy rejection instead: HTTP `403` with code `POLICY_DENIED` and a message that contains `declared signal(s) do not match the executed intent`. 1. `metadata.businessTransactionId` equals `businessTransactionId`. 2. `authorization.authorityId` equals `authority.authorityId`. 3. `intent.authorizationId` equals `authorization.authorizationId`. 4. `policy.name`, `policy.version` and `intent.action` are not empty. 5. Every `businessTransactionId` is a valid UUID. 6. Where the policy binds a signal to an intent value (a `boundSignals` entry), the signal must equal that value exactly. For example the refund policy binds `signals.refundAmount` to `intent.parameters.amount`, so both must be the same number. ### A complete example This is a real request shape for the `customer-refund` policy. Replace every UUID with a new one, and the timestamps with the current time. ```json { "businessTransactionId": "5b1c0d2e-3f4a-4b5c-8d6e-7f8091a2b3c4", "metadata": { "businessTransactionId": "5b1c0d2e-3f4a-4b5c-8d6e-7f8091a2b3c4" }, "authority": { "authorityId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "authorityType": "SERVICE", "principalId": "my-agent", "issuedAt": "2026-09-20T10:00:00.000Z" }, "authorization": { "authorizationId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f", "authorityId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "purpose": "Refund a customer for a cancelled order", "issuedAt": "2026-09-20T10:00:00.000Z" }, "intent": { "intentId": "3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "authorizationId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f", "action": "erp:invoice-pay", "target": "ORDER-1001", "parameters": { "orderId": "ORDER-1001", "transactionId": "TXN-1001", "amount": 5 }, "createdAt": "2026-09-20T10:00:00.000Z" }, "policy": { "name": "customer-refund", "version": "1.2.0", "schemaVersion": "1.0.0" }, "signals": { "refundEligible": true, "managerApproved": false, "fraudCheckPassed": true, "refundAmount": 5 } } ``` Sent as it is, this example is refused with `403 POLICY_DENIED`, because `managerApproved` is `false` and every refund needs a signed manager approval. That refusal is the normal first step: it is what tells a person to approve. The version with the approval is below. **Never set a signal to `true` unless you have checked it is true.** A policy trusts the signals you send for some facts, so a false `true` produces an authorization that should not exist. **Approval signals are different.** For each signal in `APPROVAL_SIGNALS`, send `false` unless you hold a signed approval for this exact action. The server does not believe `true` on its own: it checks the signed approval, and refuses the request without one. Step 6 says how to get one. With a signed approval, send the signal as `true` and put the approval, exactly as you received it, in `signals.approvalArtifact`: ```json "signals": { "refundEligible": true, "fraudCheckPassed": true, "refundAmount": 5, "managerApproved": true, "approvalArtifact": { "payload": { "...": "..." }, "signature": { "...": "..." } } } ``` ## Step 5: send it **Do:** send `POST {PARMANA_ENDPOINT}/execute` with the header, `Content-Type: application/json`, and the object from step 4. **Set a client timeout of at least 120 seconds.** The request runs the whole pipeline before it answers, including the call to the connector. SDKs' default of 30 seconds: pass `timeout: 120_000` (TypeScript) or `timeout=120` (Python) to the client. **Never retry this request automatically.** A retry could repeat a real action. The rules for a timeout are in step 7. ## Step 6: read the answer Apply the **first** row that matches. Every error body is `{"error": ""}`, with a `code` when there is one. | You receive | Meaning | Do | | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP `200`, and `executions[0].decision.outcome` is `APPROVED` | Approved and released. You have a signed Execution Trust Record. | Go to step 7, then proceed. | | HTTP `403`, code `POLICY_DENIED`, and the message says the version was superseded | A newer policy version took effect after step 3. | Go back to step 3, then send again with a **new** `businessTransactionId`. | | HTTP `403`, code `POLICY_DENIED`, you sent an approval signal as `false`, and every other signal you sent is true | The action needs a person's signed approval. Nothing was executed. | Go to [If the action needs a person's approval](#if-the-action-needs-a-persons-approval). | | HTTP `403`, code `POLICY_DENIED` | A policy rule refused. Final. | Do not proceed. Do not retry. Report the message to the operator. | | HTTP `403`, code `CAPABILITY_NOT_ALLOWED` | Your key may not invoke this action. | Stop. Ask the operator to grant it. | | HTTP `403`, no code | Your key may not assert that `principalId`. | Use your `callerId`, or stop and ask. | | HTTP `401` | Key missing or wrong. | Stop. Ask for a valid key. | | HTTP `400` | The request is malformed. The message names the problem. | Fix the request. Use a **new** `businessTransactionId`. | | HTTP `404` | The policy was not found. | Stop. Go back to step 3. | | HTTP `409` | That `businessTransactionId` was already used. | Do not resend. Go to step 7 to look up what happened. | | HTTP `429` | Rate limited. Nothing was recorded. | Wait the seconds in the `Retry-After` header, then send again with a **new** `businessTransactionId`. | | HTTP `503`, code `SIGNING_UNAVAILABLE`, `EXECUTION_INTENT_UNAVAILABLE` or `AUDIT_UNAVAILABLE` | Refused before release. **Nothing was executed.** | Wait, then retry with a **new** `businessTransactionId`. If it keeps happening, tell the operator. | | HTTP `500`, code `EXECUTION_RECORD_INCOMPLETE` | The action **was** released, but its record could not be produced. | **Do not resend under any id.** Go to step 7. Tell the operator now. The operator can rebuild the signed record without repeating the action, see [Execution Intents](/concepts/execution-intents). | | HTTP `502`, code `EXECUTION_OUTCOME_UNKNOWN` | The action was released and the connector call failed. It **may** have been performed. | **Do not resend under any id.** Tell the operator, who checks the target system and closes the Execution Intent. | | Any other `5xx`, a timeout, or no response | Unknown. | Do not proceed. Go to step 7. | ## If the action needs a person's approval A refusal for want of an approval is not a failure. Parmana does not hold the request open; you send a new one once a person has approved. 1. **Tell the operator** what needs approving: the `ACTION`, the resource (for a refund, the order id), the amount if there is one, and your refused `businessTransactionId`. If the deployment has approval notifications turned on, the approver was already notified with the same details. 2. **Wait for a signed approval.** It is a JSON object with `payload` and `signature`, made by the approver on their own machine. You cannot make one, and you must never ask for or hold an approver's private key. 3. **Check it matches before sending.** `payload.capability` equals `ACTION`, `payload.resourceId` equals the resource, and `payload.expiresAt` is in the future. Use that field for the lifetime. Do not assume a fixed duration. An approval works once. 4. **Send a new request** (step 3 again, then step 4) with a **new** `businessTransactionId`, the same action and amount, the approval signal `true`, and the approval in `signals.approvalArtifact`. Do not change anything else. 5. If it is refused again, do not retry with the same approval: it may be expired, used, for a different resource or amount, or from an approver the server does not trust. Report the message to the operator. **Making an approval yourself is not allowed unless the operator gives you a signing key and says, in writing, that you may approve on that server.** Without that written permission, stop and ask the operator for an approval. On any server, never ask for or hold an approver's private key. For people: [Human approval](/concepts/human-approval) and [Approval notifications](/guides/approval-notifications). ## Step 7: confirm and keep the record **After an approval (HTTP `200`),** confirm all of these in the response, then store the whole response: 1. `executions[0].decision.outcome` is `APPROVED`. 2. `verifications[0].status` is `VERIFIED`. 3. `receipts[0]` exists. If any is missing, treat the action as **not confirmed** and tell the operator. Store the response and the `businessTransactionId` together. They are your proof. **After a `409`, a timeout, no response, `EXECUTION_RECORD_INCOMPLETE` or `EXECUTION_OUTCOME_UNKNOWN`,** find out what the server recorded. Send `GET {PARMANA_ENDPOINT}/trust-records/{businessTransactionId}` with the header. | The lookup returns | Meaning | Do | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | HTTP `200` and a record | The request was processed. | Apply step 6 to the record: check `decision.outcome`, `verifications[0].status` and `receipts[0]`. | | HTTP `404` on the record, and `GET {PARMANA_ENDPOINT}/transactions/{businessTransactionId}` returns `200` | The server accepted it but has no record. It may still be running, or it failed. | Wait 30 seconds and look up once more. If still no record, **stop and tell the operator.** Do not resend. | | HTTP `404` on both | The server never recorded it. | It is safe to send again with a **new** `businessTransactionId`. | ## Rules that are never broken 1. Never reuse a `businessTransactionId`. 2. Never resend after `EXECUTION_RECORD_INCOMPLETE` or `EXECUTION_OUTCOME_UNKNOWN`, or after a timeout you have not resolved with step 7. 3. Never treat "I could not reach Parmana" as "allowed". 4. Never work around a `POLICY_DENIED` by changing the request until it passes. A denial is a decision. Tell the operator. The two exceptions are in step 6: a superseded version, and a missing approval, which a person resolves, not you. 5. Never send a signal you have not verified. 6. Never log the API key. ## Where the machine readable sources are | Source | URL | Use it for | | ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------ | | OpenAPI, JSON | `{PARMANA_ENDPOINT}/openapi.json` | Exact request and response schemas for every endpoint. | | OpenAPI, YAML | `{PARMANA_ENDPOINT}/openapi.yaml` | The same, as YAML. | | API manifest | `{PARMANA_ENDPOINT}/api-manifest.json` | The API version, the authentication scheme and the current SDK versions. | | Docs index for agents | `https://docs.parmanasystems.com/llms.txt` | A list of every documentation page with a one line description. | | Docs in full for agents | `https://docs.parmanasystems.com/llms-full.txt` | The integration pages concatenated into one file. | If you use an SDK instead of raw requests, the steps and the rules are the same. The [TypeScript SDK](/sdks/typescript) and the [Python SDK](/sdks/python) both offer a helper that builds the Business Transaction and keeps the identifiers consistent. Neither retries `POST /execute` for you. For a human reading this page, the same material with explanations is in [Full integration overview](/guides/full-integration-overview) and the [Error catalog](/api-reference/error-catalog). --- ## parmana-connect: the connector service Source: https://docs.parmanasystems.com/connectors/parmana-connect `parmana-connect` is a small Node.js service that runs one connector. Parmana decides whether an action may run and signs the decision. It then releases the action to a connector. `parmana-connect` is a ready-made connector service: it receives the signed release, verifies it, runs the call described by a manifest, and answers. It lives in its own repository, [pavancharak/parmana-connect](https://github.com/pavancharak/parmana-connect). This page describes it as an operator and a developer use it. For the protocol that connects every external connector to Parmana, read [connect any external system](/guides/connect-any-external-system). For the reasons behind the design, read [why Parmana is built this way](/why-parmana-is-built-this-way). ## What it does, in order 1. **Receives a request** at `POST /execute`. 2. **Decides which kind of request it is.** A body with `release` and `signature` is a signed release from Parmana. Anything else is treated as a signed authorization, and needs the bearer token (see "Two request shapes" below). 3. **Verifies the signed release**, with the checks listed in "The checks, in order". 4. **Runs the connector.** The connector makes the upstream HTTP call described in the manifest, using the upstream credential the service reads from its environment. 5. **Answers** with the result, in the shape Parmana expects. The service never decides policy. It checks that Parmana approved the action, and then runs exactly what was approved. ## Two request shapes | Shape | How it is recognised | Authentication | Used by | | ------------------------ | --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | **Signed release** | The body has `release` and `signature` | The signature. No bearer token | Parmana's external connector protocol, for a capability registered as an external connector | | **Signed authorization** | Any other body, with an `authorization` field | `Authorization: Bearer ` | Parmana's direct execution path, for an action sent through `HttpExecutionSystem` | Both shapes arrive at the same path, `POST /execute`. The service checks the shape first, then the matching authentication. ## The checks, in order For a signed release, the service runs these checks. It stops at the first failure and returns the failure in `errors`. 1. **Shape.** `release.version` is `1`. `businessTransactionId`, `capability`, `target`, `audience` and `expiresAt` are non-empty strings. `parameters` is an object. 2. **Signature algorithm.** `signature.algorithm` is `ed25519`. 3. **Key.** `signature.keyId` is `default`. The public key the service was given is the one checked against. 4. **Signature.** The signature is valid over the canonical serialization of `release`. Any change to the release after signing fails this check. 5. **Audience.** `release.audience` equals `PARMANA_RELEASE_AUDIENCE` exactly. This stops a release sent to one endpoint from being replayed to another. 6. **Expiry.** The release has not expired. The service allows 30 seconds of clock difference. 7. **Replay.** The `businessTransactionId` has not run before. The service records it only after every other check passes, so a release refused for another reason can still be sent again with a fresh signature. A release that passes every check runs the connector. A release that fails returns `403` with the reasons. ## The answer A successful release returns `200` with: ```json { "businessTransactionId": "", "capability": "", "success": true, "result": { "status": 200, "body": {} }, "executedAt": "" } ``` - `success` is `true` when the connector call succeeded, and `false` when it failed. Both are `200`. Parmana records either. - `result` is an object. If its serialized size is above 16 KB, the service returns `success: false` with an error saying so, because Parmana refuses results above that size. - If the connector throws, the service returns `success: false` and `result.error`, with a short message. It never returns the upstream credential. ## Settings Every setting is read from the environment. The service refuses to start if a required one is missing, and the error names the setting, never its value. | Setting | Required | Default | What it does | | ------------------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PARMANA_SERVICE_BEARER_TOKEN` | Yes | None | Shared secret for signed authorizations. At least 32 characters. | | `PARMANA_PUBLIC_KEY_FILE` | Yes | None | Path to Parmana's Ed25519 public key, in PEM. It checks both shapes. | | `PARMANA_CONNECTOR_MANIFEST` | Yes | None | Path to the connector manifest, in JSON or YAML. | | The manifest's `secretRef` name | Yes | None | The environment variable that holds the upstream credential. Its name is the `secretRef` in the manifest. | | `PARMANA_POLICY_DIR` | Yes | None | An existing folder. The crypto setup requires it. | | `PARMANA_RELEASE_AUDIENCE` | For releases | Unset | The endpoint URL exactly as registered in Parmana, for example `https://service.example.com/execute`. Must be `https`. Unset, signed releases return `503`. | | `PARMANA_NONCE_STORE` | No | `postgres` | `postgres` or `memory`. See "Replay protection". | | `PARMANA_DATABASE_URL` | With `postgres` | None | Connection string for the replay store. | | `PARMANA_SERVICE_PORT` | No | `8080` | The port to listen on. Hosts often set this for you. | | `PARMANA_SERVICE_HOST` | No | `127.0.0.1` | The address to bind. A hosted service needs `0.0.0.0`, or the host cannot reach it. | | `PARMANA_CONNECTOR_TIMEOUT_MS` | No | `10000` | How long the upstream call may take, in milliseconds. | ### The manifest The manifest says what the connector can do. A minimal one: ```json { "system": "httpbin", "baseUrl": "https://httpbin.org", "apiVersion": "1", "credential": { "type": "bearer", "secretRef": "HTTPBIN_TOKEN" }, "capabilities": [ { "id": "httpbin:get", "method": "GET", "path": "/get", "effect": "read" } ] } ``` - `system` is a short name. Every capability `id` must start with `system:`. - `baseUrl` must be `https`, must not contain credentials, and must not contain a query or fragment. - `credential.type` is `bearer` or `header`. A `header` credential also needs `headerName`. - `secretRef` is an upper-case environment variable name. The service reads the upstream value from it, never from the manifest. - Each capability has an `id`, a `method`, a `path`, and an `effect` of `read` or `write`. A `GET` cannot be a `write`. A `write` must declare its inputs. Each `{name}` in a path must be a declared, required input. ## Replay protection The replay store records every `businessTransactionId` that has run, until the release expires. - `postgres` (the default) shares the record across every instance of the service. Use it for any deployment that runs more than one instance. - `memory` keeps the record in one process. A restart forgets it, and a second instance does not see it. Use it only for one instance on your own machine or a test. ## Deploying The service needs three things from its host: a way to start it (`npm ci && npm run build`, then `npm run start`), the secret files named in its settings, and the environment variables above. On a host that mounts secret files under `/etc/secrets/`, set `PARMANA_PUBLIC_KEY_FILE` and `PARMANA_CONNECTOR_MANIFEST` to those paths. Set `PARMANA_SERVICE_HOST=0.0.0.0` and the port the host expects. Set `PARMANA_RELEASE_AUDIENCE` to the exact public URL of `/execute`, and register that same URL in Parmana. The service has no health route. Do not set a health check path to `/healthz`, because the host will mark the service unhealthy. Free hosting plans can sleep when idle. The first request after a sleep took about 50 seconds when we measured it. Parmana's releases expire 60 seconds after they are issued, so a release sent to a sleeping service can expire before it is answered. For production, use a plan that does not sleep. ## Troubleshooting | What you see | Cause | Fix | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | The service exits at start, naming a setting | A required setting is missing, or invalid | Set the named setting. The message never shows a value | | `503` with "no release audience configured" | `PARMANA_RELEASE_AUDIENCE` is unset | Set it to the exact registered URL | | `403` with `errors` containing "is not this endpoint" | The release's audience differs from `PARMANA_RELEASE_AUDIENCE` | Make the setting equal the URL registered in Parmana, character for character | | `403` with "the signature does not verify" | The release was changed after signing, or was signed by a different key | Check that `PARMANA_PUBLIC_KEY_FILE` holds the key Parmana signs with | | `403` with "the release expired" | The release is older than its expiry, allowing 30 seconds of clock difference | Check the server's clock. Ask Parmana for a new release | | `403` with "already executed" | The same `businessTransactionId` ran before | This is the replay protection working. Do not resend it as a new run | | `401` on a signed authorization | The bearer token is missing or wrong | Send `Authorization: Bearer` with the value of `PARMANA_SERVICE_BEARER_TOKEN` | | Parmana reports `502 EXECUTION_OUTCOME_UNKNOWN` for this connector | The service refused or failed the release, or was not reachable | Check the service's logs for the release. Make sure the registered URL is the full `/execute` path, not the site root | | The host reports no open port | The service listens on `127.0.0.1` | Set `PARMANA_SERVICE_HOST=0.0.0.0` | | The host sees the service on another port | `PARMANA_SERVICE_PORT` does not match the host's port | Set it to the port the host expects | | The upstream call times out | The upstream is slow, or unreachable | Raise `PARMANA_CONNECTOR_TIMEOUT_MS` within reason, or check the upstream | ## What the service does not do - It does not decide policy, and it does not approve anything. Parmana does both. - It does not store the upstream credential anywhere except its environment, and it does not return it. - It does not check the business meaning of a request. It checks that the release is authentic, addressed to it, fresh, and new, then runs the manifest's call. --- ## Why Parmana is built this way Source: https://docs.parmanasystems.com/why-parmana-is-built-this-way Parmana makes one promise: an agent's action runs only if a policy allowed it, a person approved that exact action, and a signed record shows what happened. Most of its design follows from that promise. This page explains each choice, the reason for it, and what it costs. Read [how Parmana thinks](/how-parmana-thinks) first if you want the request flow, and [the architecture overview](/architecture/overview) if you want the code layout. Each decision below links to its record in the repository. The records have the full context, the alternatives that were rejected, and the dates. ## 1. Anyone can check a decision without trusting Parmana **What it does.** Every decision produces a signed record. The public key that checks those signatures is published (`GET /keys/default`), and the verifier runs offline, on your own machine, with nothing else. **Why.** If the only way to know what happened is to trust the server, the record proves nothing to anyone who doesn't trust the server. An independent check changes that: an auditor, a regulator, or a customer can verify a decision without an account, a network call, or Parmana's cooperation. **What it costs.** Keys have to be managed carefully. A signature proves who signed a record, not that the decision was wise. Verification tells you the record is intact and was signed by the expected key, nothing more. Record: [ADR-0003, verification is independent](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0003-Verification-Is-Independent.md). Try it: [verify a record in your browser](/verification/verify-in-browser). ## 2. Evidence is added, never edited **What it does.** A record of what happened is appended to. An existing record is not changed. If something has to be corrected, the correction is a new record that refers to the old one. **Why.** An edit that leaves no trace would make the record worthless as evidence. Append-only history means a change to the past can be detected. **What it costs.** A mistake stays in the history. Corrections take another record, so the history grows. Record: [ADR-0005, evidence is append-only](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0005-Evidence-Is-Append-Only.md). See also [detect tampering](/guides/detect-tampering). ## 3. The same input gives the same decision **What it does.** A policy is a fixed set of rules. Given the same request, the same policy version and the same approval, the decision is the same. **Why.** A decision that could change between runs can't be explained or reproduced later. Determinism means an auditor can re-run a decision and get the same answer. **What it costs.** Rules must be written precisely. A rule cannot depend on something the system cannot see, such as the time of day, unless that value is passed in as a signal. Record: [ADR-0007, deterministic execution](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0007-Deterministic-Execution.md). See also [determinism and clocks](/concepts/determinism-and-clocks). ## 4. What is released is signed before it leaves **What it does.** Parmana writes an execution intent and signs it before the action is released to a connector. The record of what was about to happen exists before the action runs. **Why.** If a record is written only after the action, a failure between the two leaves an action with no record. Signing the intent first closes that gap. If the connector fails afterwards, the record still shows what was attempted. **What it costs.** One more step in the request path, and the operator has to resolve intents that end in an unknown outcome. Record: [ADR-0012, signed execution intent before release](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0012-Signed-Execution-Intent-Before-Release.md). Operator guide: [execution intents](/concepts/execution-intents). ## 5. A person approves each sensitive action **What it does.** An action that needs a human has a policy rule that is true only when an approval artifact is attached. The approval is signed by a trusted issuer, names one capability and one resource, expires, and can be used once. **Why.** Rules can say what is allowed in general. A person is needed for a specific case: this refund, this order, this change. The approval names that case, so it cannot be reused for another. **What it costs.** A person has to be available. Approvals expire, so a slow approval has to be signed again. Guide: [connect an agent](/guides/connect-an-agent). Policy rules: [policies and the decision](/concepts/policies-and-the-decision). ## 6. Two people change the rules **What it does.** A change to a policy, a connector registration, or an approval issuer is proposed by one caller and approved by a different caller. The approval needs a step-up signature from the approver's own key, which is valid for two minutes. The server refuses an approval from the same caller that proposed the change. **Why.** One person should not be able to change the rules and then approve their own change. The step-up signature means a stolen session token is not enough to approve. **What it costs.** Every change takes two people and two signatures. Urgent changes are slower. Guides: [policy governance, maker and checker](/guides/policy-governance-maker-checker) and [manage approvers](/guides/manage-approvers). ## 7. External systems are connected without a shared secret **What it does.** An operator registers a capability and the HTTPS endpoint that serves it, through the maker and checker flow. Parmana sends each approved action to that endpoint as a signed release. The endpoint verifies the signature with Parmana's public key and checks the release's audience, which must be the endpoint's own URL, and its expiry. **Why.** Sharing a secret with every connector means storing it, rotating it and risking its leak. A signature needs only the public key on the endpoint side. The audience stops a release sent to one endpoint from being replayed to another. **What it costs.** The endpoint must implement the check. The SDK helpers do this for you, and the rest of the protocol is in the connect guide. Record: [ADR-0013, generic external connector](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0013-Generic-External-Connector.md). Guide: [connect any external system](/guides/connect-any-external-system). ## 8. An operator can stop all execution, with stated limits **What it does.** An operator can trip a kill switch that refuses new execution, new transactions, policy-change approvals and sandbox approvals before any of them run. The stop is stored in Postgres, so a restart does not clear it. A reset can require a second, different operator. **Why.** An agent can act at machine speed, so the institution needs one control that halts all of it at once. Partial controls, such as refusing an action in policy or revoking a connector or an approver, stop one thing at a time. **What it costs.** The stop does not recall an action already released, so calls admitted before the trip can still complete. It halts every caller at once, not one agent. A tool an agent reaches directly, bypassing Parmana, is not stopped. The status response is not signed yet, and two-person reset has not been exercised in production with two real operator keys. Record: [claim 2.58, "An Operator Can Stop All Execution, and the Stop Survives Restarts"](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/CLAIMS.md#258-an-operator-can-stop-all-execution-and-the-stop-survives-restarts). Decision record: [ADR-0017, operator kill switch](https://github.com/pavancharak/parmana-core/blob/main/docs/internal/adr/ADR-0017-Operator-Kill-Switch.md). ## Where to go next - To try it, start with the [quickstart](/quickstart). - To connect an agent, read [connect an agent](/guides/connect-an-agent). - To check a decision yourself, read [verify independently](/guides/verify-independently). - When something fails, read [troubleshooting](/troubleshooting). --- ## Troubleshooting Source: https://docs.parmanasystems.com/troubleshooting ## `npm run