Connect any external system

​

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 comes from the table below or from a response.
4. The endpoint acts only on what a verified release names. It never acts on a request that did not come from Parmana.
5. Two different people propose and approve every change. One person holding both keys defeats the control.

​

Inputs you need before you start

​

Step 1: check the server

​

Step 2: write the policy

{
  "policyId": "erp-invoice",
  "policyVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "description": "Creates an invoice in the ERP only with a signed approval from a trusted person for that customer.",
  "signalsSchema": {
    "invoiceApproved": "boolean",
    "customerActive": "boolean"
  },
  "approvalSignals": {
    "invoiceApproved": { "resourceId": "target", "value": "parameters.amount" }
  },
  "unboundSignalReasons": {
    "customerActive": "Declared by the caller. It can refuse an invoice, never authorize one on its own."
  },
  "rules": [
    {
      "id": "reject-inactive-customer",
      "condition": { "fact": "customerActive", "operator": "is_false" },
      "outcome": { "action": "reject", "reason": "The customer is not active." }
    },
    {
      "id": "approve-with-approval",
      "condition": {
        "all": [
          { "fact": "invoiceApproved", "operator": "is_true" },
          { "fact": "customerActive", "operator": "is_true" }
        ]
      },
      "outcome": {
        "action": "approve",
        "reason": "Invoice approved by a trusted person for this customer."
      }
    },
    {
      "id": "reject-approval-required",
      "condition": { "always": true },
      "outcome": {
        "action": "reject",
        "reason": "An invoice needs a signed approval for this customer in signals.approvalArtifact, with invoiceApproved true."
      }
    }
  ]
}

​

Step 3: propose the policy (maker)

1. 400: the policy is refused, and the message says why (for example, an approve rule that does not require the approval signal). Fix the file, then repeat this step.
2. 403 NON_HUMAN_CALLER_DENIED: PROPOSER_KEY is not a human key. Stop. Ask the operator.
3. 409 CONFLICT: a proposal for this version is already open. Approve or reject it first.

​

Step 4: approve the policy (checker)

​

Step 5: run the endpoint

• TypeScript: typescript/examples/07-external-connector-endpoint.ts, createReleaseHandler({ publicKeys, audience, act }).
• Python: python/examples/13_external_connector_endpoint.py, create_release_handler(public_keys=..., audience=..., act=...).

{
  "businessTransactionId": "<from the release>",
  "capability": "<from the release>",
  "success": true,
  "result": { "invoiceId": "INV-991" },
  "executedAt": "2026-10-01T10:00:02.000Z"
}

​

Step 6: propose the registration (maker)

curl -s -X POST $PARMANA_URL/external-connectors/changes \
  -H "Authorization: Bearer $PROPOSER_KEY" -H "Content-Type: application/json" \
  -d '{
    "action": "register",
    "capability": "erp:create-invoice",
    "endpointUrl": "https://erp.example.com/parmana/release",
    "policy": "erp-invoice",
    "allowedParameters": ["amount", "currency"],
    "timeoutMs": 10000,
    "reason": "Finance creates invoices in the ERP through Parmana."
  }'

1. 400 INVALID_EXTERNAL_CONNECTOR: a field is malformed, or the namespace belongs to a built in connector. The message names the field.
2. 400 EXTERNAL_ENDPOINT_ADDRESS_REFUSED: the endpoint is not https, names an IP address or localhost, does not resolve, or resolves to an address that is not public. Fix the host.
3. 409 CONFLICT: the capability already has an active registration (revoke it first, see below), or a change for it is already pending.

​

Step 7: approve the registration (checker)

npx tsx scripts/sign-policy-change-step-up.ts \
  --private-key-file step-up.private.pem --key-id <approver caller id> \
  --pending-policy-change-id "$CHANGE_ID" --action approve > signed.txt

curl -s -X POST $PARMANA_URL/external-connectors/changes/$CHANGE_ID/approve \
  -H "Authorization: Bearer $APPROVER_KEY" -H "Content-Type: application/json" \
  -d "{\"stepUpAuthorization\":$(grep '^{' signed.txt)}"

1. 400 EXTERNAL_ENDPOINT_ADDRESS_REFUSED: the host now resolves to an address that is not public. The address is checked again at approval. Fix the DNS or reject the change.
2. 403 (SAME_ACTOR_CANNOT_APPROVE_OWN_CHANGE or STEP_UP_AUTHORIZATION_INVALID): as in step 4.
3. 409 CONFLICT: the change was already resolved, or another registration became active.

​

Step 8: check the policy in effect for the capability

1. 409 NO_APPROVED_POLICY_VERSION: no version of POLICY_NAME is approved. Do steps 3 and 4. Every request is refused until then.
2. 404 CAPABILITY_NOT_BOUND: the registration is not active. Check step 7.
3. 503 POLICY_VERSION_UNAVAILABLE: the server could not read it. Try again; if it persists, tell the operator.

​

Step 9: grant the capability to the agent’s key (operator)

​

Step 10: make sure an approver is trusted

​

Step 11: send requests

npx tsx scripts/sign-approval.ts \
  --private-key-file <approver private key> --approver-id <approverId> --key-id <keyId> \
  --capability erp:create-invoice --resource-id customer-42 --max-amount 1200 --out approval.json

1. 503 CONNECTOR_NOT_REGISTERED: there is no active registration for the capability. Nothing was sent. Check step 7.
2. 502 EXECUTION_OUTCOME_UNKNOWN: the release failed. The endpoint may have acted: it answered something other than 200, timed out, answered without echoing businessTransactionId and capability, or its result was not an object of at most 16 KB. A request naming a parameter outside PARAMETERS, or an endpoint whose host now resolves to a non public address, is also reported this way, although nothing was sent. Do not resend as a new transaction. Check the endpoint’s own record, then close the Execution Intent with POST /execution-intents/{businessTransactionId}/resolve.
3. Any refusal before release (403, 400): as in Integrate Parmana, step 6.

​

Change or remove a connector

• Move to a new endpoint: propose {"action":"revoke","capability":"...","reason":"..."}, approve it (step 7), then register the new endpoint (steps 6 and 7). From the approved revoke until the new registration is approved, requests are refused with 503 CONNECTOR_NOT_REGISTERED.
• Change the policy: propose and approve a new version of POLICY_NAME (steps 3 and 4). It takes effect at once; the registration does not change.
• Stop it: revoke it. Nothing is deleted: GET /external-connectors keeps listing it as revoked, so every release ever made to it stays explainable.

​

Rules that are never broken

• Parmana releases only to an https host that resolves only to public addresses, checked when the registration is proposed, when it is approved, and at every release. It connects to the address it checked and follows no redirect.
• A release names one capability, target and parameter set a person approved, is addressed to one endpoint, and expires 60 seconds after it is issued. No shared secret is involved: the signature is the authentication.
• What the endpoint answers is its claim, not proof that it acted (docs/VERIFICATION-GAPS.md G-82).

​

See it run

• Tutorial 123: npx tsx examples/tutorials/123-external-connector/run.ts registers an ERP endpoint through maker checker, releases to the TypeScript example endpoint, answers a retry once, refuses a release for another endpoint, and stops at a revoke.
• The /external-connectors operations in the API reference, with real responses for every refusal.
• The design and its security reasoning: docs/adr/ADR-0013-Generic-External-Connector.md.