Policy Governance

Approve a pending policy change (checker)

Approves a Pending Policy Change (checker). Requires, in order, all fail-closed: a human-authenticated caller distinct from the proposer (maker != checker, 403 SAME_ACTOR_CANNOT_APPROVE_OWN_CHANGE otherwise), and a valid step-up authorization envelope proving fresh, explicit intent (403 STEP_UP_AUTHORIZATION_INVALID on a missing, malformed, expired, replayed, wrong-id, wrong-action, or wrong-key-signed envelope). Once both pass, this writes the live policies///policy.json file and records a signed PolicyChangeApprovalRecord BEFORE marking the change APPROVED, so a failure partway through never leaves a pending change falsely resolved with no corresponding live effect. Per-check step-up diagnostic detail is logged server-side only, never in this response.

POST

policies

pending-changes

{id}

approve

Approve a pending policy change (checker)

curl --request POST \
  --url http://localhost:3000/policies/pending-changes/{id}/approve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "stepUpAuthorization": {
    "payload": {
      "version": 1,
      "nonce": "343ee454-92c6-4ef9-9cfe-e98329e51f53",
      "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
      "action": "approve",
      "authorizedAt": "2026-09-15T03:47:51.939Z",
      "expiresAt": "2026-09-15T03:49:51.939Z"
    },
    "signature": "keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==",
    "keyId": "human-checker-step-up-key",
    "algorithm": "ed25519"
  }
}
'

import requests

url = "http://localhost:3000/policies/pending-changes/{id}/approve"

payload = { "stepUpAuthorization": {
        "payload": {
            "version": 1,
            "nonce": "343ee454-92c6-4ef9-9cfe-e98329e51f53",
            "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
            "action": "approve",
            "authorizedAt": "2026-09-15T03:47:51.939Z",
            "expiresAt": "2026-09-15T03:49:51.939Z"
        },
        "signature": "keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==",
        "keyId": "human-checker-step-up-key",
        "algorithm": "ed25519"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    stepUpAuthorization: {
      payload: {
        version: 1,
        nonce: '343ee454-92c6-4ef9-9cfe-e98329e51f53',
        pendingPolicyChangeId: '6f4e4020-adf5-4449-938d-27aab58f66b7',
        action: 'approve',
        authorizedAt: '2026-09-15T03:47:51.939Z',
        expiresAt: '2026-09-15T03:49:51.939Z'
      },
      signature: 'keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==',
      keyId: 'human-checker-step-up-key',
      algorithm: 'ed25519'
    }
  })
};

fetch('http://localhost:3000/policies/pending-changes/{id}/approve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/policies/pending-changes/{id}/approve",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'stepUpAuthorization' => [
        'payload' => [
                'version' => 1,
                'nonce' => '343ee454-92c6-4ef9-9cfe-e98329e51f53',
                'pendingPolicyChangeId' => '6f4e4020-adf5-4449-938d-27aab58f66b7',
                'action' => 'approve',
                'authorizedAt' => '2026-09-15T03:47:51.939Z',
                'expiresAt' => '2026-09-15T03:49:51.939Z'
        ],
        'signature' => 'keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==',
        'keyId' => 'human-checker-step-up-key',
        'algorithm' => 'ed25519'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3000/policies/pending-changes/{id}/approve"

	payload := strings.NewReader("{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/policies/pending-changes/{id}/approve")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/policies/pending-changes/{id}/approve")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
  "policyName": "openapi-capture-demo",
  "policyVersion": "1.0.0",
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "proposedBy": "human-maker",
  "proposedAt": "2026-09-15T03:47:13.920Z",
  "status": "APPROVED",
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec",
  "resolvedBy": "human-checker",
  "resolvedAt": "2026-09-15T03:48:03.586Z"
}

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.

Path Parameters

string

required

Body

application/json

Request body for POST /policies/pending-changes/{id}/approve.

stepUpAuthorization

Policy Change Step-Up Authorization · object

required

Signed envelope proving a checker's explicit, fresh intent to approve or reject one specific Pending Policy Change (Policy Governance, Layer 4). Produced by PolicyChangeStepUpAuthorizationSigner (@parmana/crypto) using the checker's own step-up private key, never the bearer API key. Verified server-side against: the checker's registered stepUpPublicKey, payload.pendingPolicyChangeId matching the URL's {id}, payload.action matching the endpoint (approve vs reject), payload.expiresAt not yet passed, and payload.nonce not previously seen (single-use, replay-rejected on a second attempt with the same envelope).

Show child attributes

Example:

{
  "payload": {
    "version": 1,
    "nonce": "343ee454-92c6-4ef9-9cfe-e98329e51f53",
    "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
    "action": "approve",
    "authorizedAt": "2026-09-15T03:47:51.939Z",
    "expiresAt": "2026-09-15T03:49:51.939Z"
  },
  "signature": "keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==",
  "keyId": "human-checker-step-up-key",
  "algorithm": "ed25519"
}

Response

Approved. The live policy.json file has been written.

A proposed change to a policy's content, held in a durable pending state until a second, distinct human explicitly approves or rejects it (Policy Governance, maker-checker). Only ever moves from PENDING_APPROVAL to APPROVED or REJECTED, exactly once.

pendingPolicyChangeId

string

required

Unique Pending Policy Change identifier.

policyName

string

required

The policy this proposal targets, same identifier as Policy.policyId.

policyVersion

string

required

The existing version this proposal is a change against ("the version being replaced"). Not necessarily equal to proposedContent's own declared version: an in-place patch and a version bump are both legitimate.

proposedContent

object

required

The full proposed policy.json content, in its entirety, not a diff or patch.

proposedBy

string

required

Identity of the proposer (maker). Always a human-authenticated (credentialHolderType USER) caller.

proposedAt

string<date-time>

required

status

enum<string>

required

Available options:

PENDING_APPROVAL,

APPROVED,

REJECTED

reason

string

required

Free-text justification from the proposer, required at creation.

resolvedBy

string

Identity of the resolver (checker). Absent while PENDING_APPROVAL. Never equal to proposedBy.

resolvedAt

string<date-time>

Absent while PENDING_APPROVAL.

rejectionReason

string

Present only when status is REJECTED.

coverageWarnings

string[]

Present only when non-empty: uncovered-fact warnings from PolicyValidator.findUncoveredFacts against proposedContent.

ruleConflicts

string[]

Present only when non-empty: advisory rule-conflict warnings from PolicyValidator.findRuleConflicts against proposedContent, never blocking.

Approve a pending policy change (checker)

curl --request POST \
  --url http://localhost:3000/policies/pending-changes/{id}/approve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "stepUpAuthorization": {
    "payload": {
      "version": 1,
      "nonce": "343ee454-92c6-4ef9-9cfe-e98329e51f53",
      "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
      "action": "approve",
      "authorizedAt": "2026-09-15T03:47:51.939Z",
      "expiresAt": "2026-09-15T03:49:51.939Z"
    },
    "signature": "keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==",
    "keyId": "human-checker-step-up-key",
    "algorithm": "ed25519"
  }
}
'

import requests

url = "http://localhost:3000/policies/pending-changes/{id}/approve"

payload = { "stepUpAuthorization": {
        "payload": {
            "version": 1,
            "nonce": "343ee454-92c6-4ef9-9cfe-e98329e51f53",
            "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
            "action": "approve",
            "authorizedAt": "2026-09-15T03:47:51.939Z",
            "expiresAt": "2026-09-15T03:49:51.939Z"
        },
        "signature": "keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==",
        "keyId": "human-checker-step-up-key",
        "algorithm": "ed25519"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    stepUpAuthorization: {
      payload: {
        version: 1,
        nonce: '343ee454-92c6-4ef9-9cfe-e98329e51f53',
        pendingPolicyChangeId: '6f4e4020-adf5-4449-938d-27aab58f66b7',
        action: 'approve',
        authorizedAt: '2026-09-15T03:47:51.939Z',
        expiresAt: '2026-09-15T03:49:51.939Z'
      },
      signature: 'keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==',
      keyId: 'human-checker-step-up-key',
      algorithm: 'ed25519'
    }
  })
};

fetch('http://localhost:3000/policies/pending-changes/{id}/approve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/policies/pending-changes/{id}/approve",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'stepUpAuthorization' => [
        'payload' => [
                'version' => 1,
                'nonce' => '343ee454-92c6-4ef9-9cfe-e98329e51f53',
                'pendingPolicyChangeId' => '6f4e4020-adf5-4449-938d-27aab58f66b7',
                'action' => 'approve',
                'authorizedAt' => '2026-09-15T03:47:51.939Z',
                'expiresAt' => '2026-09-15T03:49:51.939Z'
        ],
        'signature' => 'keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==',
        'keyId' => 'human-checker-step-up-key',
        'algorithm' => 'ed25519'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3000/policies/pending-changes/{id}/approve"

	payload := strings.NewReader("{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/policies/pending-changes/{id}/approve")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/policies/pending-changes/{id}/approve")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stepUpAuthorization\": {\n    \"payload\": {\n      \"version\": 1,\n      \"nonce\": \"343ee454-92c6-4ef9-9cfe-e98329e51f53\",\n      \"pendingPolicyChangeId\": \"6f4e4020-adf5-4449-938d-27aab58f66b7\",\n      \"action\": \"approve\",\n      \"authorizedAt\": \"2026-09-15T03:47:51.939Z\",\n      \"expiresAt\": \"2026-09-15T03:49:51.939Z\"\n    },\n    \"signature\": \"keOXnzUk8KcGrQTkpXC4Ki8ps3GTvMANwqq96b+toxba07gjkcmpyL/vaPZ7+pPZ1HAOJOOy3rj5XfhcwOTnAw==\",\n    \"keyId\": \"human-checker-step-up-key\",\n    \"algorithm\": \"ed25519\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
  "policyName": "openapi-capture-demo",
  "policyVersion": "1.0.0",
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "proposedBy": "human-maker",
  "proposedAt": "2026-09-15T03:47:13.920Z",
  "status": "APPROVED",
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec",
  "resolvedBy": "human-checker",
  "resolvedAt": "2026-09-15T03:48:03.586Z"
}

Get Started

Core Concepts

Guides

SDKs

REST API

Security & Deployment

Integrations

Tutorials

Advanced

Support

Changelog

Approve a pending policy change (checker)

Authorizations

Path Parameters

Body

Response