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

Accepted and recorded as RECEIVED. Nothing has been released.

businessTransactionId
string<uuid>
required
status
enum<string>
required
Available options:
RECEIVED
transaction
object
required

The Business Transaction as stored.

acceptedAt
string<date-time>