Skip to main content
POST
cURL

Authorizations

Authorization
string
header
default:2VfYWCzt_cBAPK-8uufX6ordfY2JuQhFPsohuEumKME
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 body for POST /business-signal-sources/changes. A register carries endpointUrl and optionally timeoutMs, publicKeyPem and keyId; a revoke carries none of them.

action
enum<string>
required
Available options:
register,
revoke
name
string
required
Pattern: ^[a-z0-9][a-z0-9-]{0,62}$
reason
string
required
Required string length: 1 - 2000
endpointUrl
string

Required for register. https only, a public host name.

Maximum string length: 2048
timeoutMs
integer
default:10000
Required range: 1000 <= x <= 30000
publicKeyPem
string

Optional, register only. An Ed25519 public key in PEM. Recommended: without it, Parmana trusts the answer on the strength of the pinned HTTPS connection alone.

Maximum string length: 1000
keyId
string

Optional, register only, and only with publicKeyPem.

Pattern: ^[A-Za-z0-9._-]{1,128}$

Response

Proposed and waiting for a checker. Keep the changeId.

Response of POST /business-signal-sources/changes (201) and of approve and reject (200). A bare Business Signal Source Change, no wrapper.

changeId
string
required

Unique id of the change, a UUID. The step up authorization for approve or reject names it in payload.pendingPolicyChangeId. An approved register change's id is also the registrationId.

action
enum<string>
required

register names a source and its endpoint; revoke ends the active registration for the name.

Available options:
register,
revoke
name
string
required

The name a policy's signalSources uses in source.

Pattern: ^[a-z0-9][a-z0-9-]{0,62}$
reason
string
required

Why, from the proposer.

Maximum string length: 2000
proposedBy
string
required

The proposer's caller id. Always a human credential.

proposedAt
string<date-time>
required
status
enum<string>
required

PENDING_APPROVAL until a second person approves or rejects it; then APPROVED or REJECTED, once.

Available options:
PENDING_APPROVAL,
APPROVED,
REJECTED
endpointUrl
string

register only. The endpoint as the server stored it, normalized by URL parsing: https, a host name with a domain, no IP literal, no localhost, no user name, password or fragment, resolving only to public addresses.

timeoutMs
integer

register only. How long Parmana waits for the source's answer. Defaults to 10000.

Required range: 1000 <= x <= 30000
publicKeyPem
string

register only, optional. The Ed25519 public key the source signs its answers with, as the server stored it (SPKI PEM).

keyId
string

register only, optional, and only with publicKeyPem.

Pattern: ^[A-Za-z0-9._-]{1,128}$
resolvedBy
string

Who approved or rejected it. Never the proposer.

resolvedAt
string<date-time>
rejectionReason
string

Present when REJECTED.