Skip to main content
POST
cURL

Authorizations

​
Authorization
string
header
required

Caller API key issued by scripts/generate-api-key.ts. Sent as Authorization: Bearer . Verified against a stored SHA-256 hash in constant time by packages/api/src/auth/StaticKeyAuthenticator.ts. Required on every route not listed as exempt in this document's top-level description. See /api-reference/authentication.

Body

application/json

Request payload for POST /execute and POST /transactions. status and createdAt are assigned by Parmana and must not be supplied by the client. Validation performed identically by both endpoints (each has its own inline businessTransactionId UUID check, then shares BusinessTransactionMapper.fromRequest and BusinessTransactionValidator): metadata.businessTransactionId must equal businessTransactionId; authorization.authorityId must equal authority.authorityId; intent.authorizationId must equal authorization.authorizationId; policy.name, policy.version, and intent.action must each be non-empty. No other structural validation is performed: authority, authorization, intent, policy, and signals objects are otherwise passed through as supplied, including any additional properties.

​
businessTransactionId
string<uuid>
required

Unique Business Transaction identifier. Must be a valid UUID on both POST /execute and POST /transactions (rejected with 400 otherwise).

​
metadata
Metadata · object
required

Immutable Business Transaction metadata supplied by the calling application. Not evaluated by Policy. businessTransactionId is the only required field; it must match the top-level businessTransactionId. Parmana rejects a mismatch with a 400.

Example:
​
authority
Authority · object
required

Entity empowered to authorize execution within a trust domain. Immutable once issued.

Example:
​
authorization
Authorization · object
required

Immutable trust artifact proving that an Authority granted approval for an intended execution.

Example:
​
intent
Intent · object
required

Immutable declaration of the action an Authority intends to be executed under an Authorization.

Example:
​
policy
Policy Reference · object
required

Exact Policy to evaluate. The client explicitly supplies name, version, and schemaVersion; Parmana does not automatically discover or select a policy. If no matching policy file exists at policies/{name}/{version}/policy.json, the request fails with a 404 (policyId/policyVersion on POST /policies/validate) or a RUNTIME_ERROR (name/version elsewhere, from PolicyNotFoundError not otherwise mapped by the shared error handler in every route, see the error envelope note).

Examples:
​
signals
Signals · object
required

Opaque runtime facts evaluated by the resolved Policy's rules. Parmana assigns no business meaning to these values and does not statically validate them beyond the Policy's own signalsSchema declaration (see policies/{name}/{version}/policy.json). Scaled integers, not floats, for numeric signals such as amounts (house convention across every reference policy).

Example:

Response

Approved and released. The body is the signed Execution Trust Record.

Response returned by POST /execute, POST /transactions, and GET /trust-records/{businessTransactionId}. A bare Execution Trust Record, no wrapper. POST /execute returns this with status 200; POST /transactions returns the identical shape with status 201.

​
trustRecordId
string
required

Unique Execution Trust Record identifier.

​
businessTransactionId
string
required

Business Transaction identifier.

​
transaction
Business Transaction · object
required

Canonical immutable business context accepted by Parmana for execution: Authority -> Authorization -> Intent -> Business Transaction -> Policy. Every Business Transaction produces exactly one Decision, one Execution, and one Execution Trust Record.

Example:
​
overrides
Override · object[]
required

Override history. Append-only; empty on every transaction in this repository today (no route creates an Override).

​
executions
Execution · object[]
required

Execution history. Append-only.

​
verifications
Verification · object[]
required

Verification history. Append-only.

​
receipts
Receipt · object[]
required

Receipt history. Append-only.

​
trustRecordHash
string
required

Canonical hash of the Execution Trust Record, computed over its canonical serialized form.

​
signature
object
required

Cryptographic signature over the canonical Execution Trust Record, proving it was produced by Parmana and has not been modified since signing.

​
createdAt
string<date-time>
required

UTC timestamp when the Execution Trust Record was first created.

​
updatedAt
string<date-time>
required

UTC timestamp when the Execution Trust Record was last extended with a new immutable artifact.

​
evidenceAnchor
object

Explicit binding linking policy-governance provenance (transaction.policy.contentHash/governanceAnchor) to what a connector actually did (executions[].evidence.attributes.connector). Not a new cryptographic guarantee on its own -- both were already covered by trustRecordHash/signature -- but a single, explicitly-named pointer an auditor can check without reconstructing the binding themselves. Absent on a Trust Record built before this field existed.