Skip to main content
POST

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 body for POST /external-connectors/changes. A register carries endpointUrl, policy, allowedParameters and optionally timeoutMs; a revoke carries none of them.

​
action
enum<string>
required
Available options:
register,
revoke
​
capability
string
required
Maximum string length: 128
Pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*:[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$
​
reason
string
required
Required string length: 1 - 2000
​
endpointUrl
string

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

Maximum string length: 2048
​
policy
string

Required for register.

Pattern: ^[a-z0-9][a-z0-9-]{0,127}$
​
allowedParameters
string[]

Required for register. May be empty.

Maximum array length: 64
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
​
timeoutMs
integer
default:10000
Required range: 1000 <= x <= 30000

Response

Proposed, PENDING_APPROVAL.

A proposal to register an external connector, or to revoke the active one for a capability, and its resolution (ADR-0013). One person proposes it; a different person approves or rejects it with a step up authorization. Only an approved change affects which external connectors are registered.

​
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 binds the capability to the endpoint; revoke ends the active registration for the capability.

Available options:
register,
revoke
​
capability
string
required

namespace:verb. Never in a built in connector's namespace (paytm, hubspot, github, slack, test).

Maximum string length: 128
Pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*:[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$
​
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. It is the audience of every release to this endpoint.

​
policy
string

register only. The name of the policy that governs the capability. The version in effect is decided by policy governance.

Pattern: ^[a-z0-9][a-z0-9-]{0,127}$
​
allowedParameters
string[]

register only. The only parameter names Parmana will forward to the endpoint.

Maximum array length: 64
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
​
timeoutMs
integer

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

Required range: 1000 <= x <= 30000
​
resolvedBy
string

Who approved or rejected it. Never the proposer.

​
resolvedAt
string<date-time>
​
rejectionReason
string

Present when REJECTED.