History and Policy Access Operations

These application programming interface (API) operations read policy history and manage owner/editor access. Use the configured POLICY_API and protected POLICY_AUTH_HEADER file from authentication. Every operation requires the policy_id path string. Set POLICY_ID to the intended policy identifier before running the examples. None uses a general If-Match or Idempotency-Key contract.

A policy grant provides owner/editor access to that policy. It does not create command capabilities such as review, approval, or audit. History distinguishes draft saves, approvals, background recompilation, and delivery requests.

GET /policies/{policy_id}/access-grants

Require policy:view and accept no body. The optional boolean active_only query parameter defaults to true.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/access-grants?active_only=true"

Return 200 with {"grants":[...]}. Each grant has integer id, policyId, subjectType, subjectId, accessLevel, grantedBy, grantedAt, nullable revokedBy, and nullable revokedAt. subjectType uses user or role. accessLevel uses owner or editor. An empty result does not independently establish policy existence. Identity or capability failures return 401 or 403. Invalid query values return 422.

POST /policies/{policy_id}/access-grants

Require active policy ownership or an authorized audited recovery override. An editor grant does not authorize grant management. Creation never grants approval or review capability.

The application/json body rejects extra fields:

For subjectType: user, use the recipient’s exact gateway-verified login username. For subjectType: role, use an authority the gateway actually forwards for the intended accounts. This authority can be a permission name, rather than a role name. Do not substitute a Protegrity Provisioned Cluster (PPC) opaque account or role identifier, display name, or authoring-catalog runtime principal. Ask a PPC user with administrator permissions to confirm the relevant identity mapping. Never supply or spoof gateway identity headers.

Replace the example username alex with the intended recipient’s verified login username before running this request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data '{"subjectType":"user","subjectId":"alex","accessLevel":"editor"}' \
  "${POLICY_API}/policies/${POLICY_ID}/access-grants"

Return 201 with the grant object described above. Policy derives grantedBy from trusted identity. Creation and listing confirm grant persistence, not the recipient’s effective access. Policy matches user subjects to verified usernames and role subjects to forwarded authorities. It does not translate PPC account or role identifiers into these values. During an approved handoff, have the recipient confirm intended access through the supported workflow using their own authenticated account. Keep command capabilities separate from owner/editor grants. Return 401 or 403 for identity or ownership failures, 404 for an unknown policy, 409 for duplicate grants or noneditable policies, or 422 for malformed bodies. Display-only imported policies cannot receive grants. After a timeout, list existing grants before repeating creation.

DELETE /policies/{policy_id}/access-grants/{grant_id}

Revoke an active grant without erasing its history. Require active ownership or an authorized audited recovery override. The required grant_id path parameter uses an integer. Accept no body or query parameters.

Set GRANT_ID to the integer id returned when listing the intended grant. Do not substitute its subject identifier.

curl --fail-with-body -X DELETE \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/access-grants/${GRANT_ID}"

Return 200 with the grant object, including revoker and revocation time. Return 401 or 403 for identity or ownership failures. Return 404 for an unknown grant, or 409 when revocation would remove the last active owner. Invalid path values return 422. List grants with active_only=false to check the revoked grant and its revocation time. If this is the last active owner, grant ownership to the intended replacement user first. Confirm the new active grant and the replacement’s intended ownership access before retrying revocation. Have the replacement use their own authenticated account through the approved ownership-management workflow. Do not remove the previous owner’s access based only on a saved grant.

GET /policies/{policy_id}/versions

Inspect the compatibility version chain. Accept no body, query parameters, or additional command capability. Gateway access rules still apply.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/versions"

Return 200 with an oldest-first array of full policy objects. Each object includes id, version, status, and authored policy fields. These versions do not replace governed revision or draft snapshot identifiers. Return 404 when no policy versions exist. Gateway failures can return 401 or 403.

GET /policies/{policy_id}/history

Read newest-first lifecycle activity without a mutation body. The backend permits optional identity for this compatibility read. Gateway access rules still apply. Reasons require policy:audit or policy:review. Other readers receive redacted reasons.

The following table describes the supported history pagination parameters:

curl --fail-with-body -i -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/history?limit=20&offset=0"

Return 200 with an array of history entries. Use X-History-Truncated and X-Next-Offset to continue a truncated page. The default window contains at most 100 entries. When the response indicates truncation, request the returned X-Next-Offset with the same limit. Read subsequent pages before treating the history as complete.

The following table summarizes fields returned in each history entry:

Fields can contain null values when they do not apply to that event. Use draftVersionId for a saved snapshot, revisionId for governed identity, and governedRevisionNumber for its major revision number. A minorVersion identifies compiled output within a governed revision. Do not substitute compatibility versionNumber for these lineage fields. Automatic recompilation can add compilation minors without changing author intent. Do not attribute system compilation events to another human approval. Return 404 for an unknown policy and 422 for invalid pagination. Gateway failures can return 401 or 403.

GET /policies/{policy_id}/audit-export

Require policy:audit and accept no body. Use the same optional limit range and nonnegative offset as history. The default window remains bounded to 100 entries.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/audit-export?limit=20&offset=0"

Return 200 with an array of compliance records. Records include policyId, revisionNumber, minorVersion, sourceLegacyVersionNumber, sourceRevision, action, actor, reason, and timestamp. Where applicable, records also include artifactFingerprint, deploymentGeneration, deploymentFingerprint, deploymentId, priorEnforcementState, and enforcementState. Governed records can include principals, classifications, enforcement decisions, and protection actions. The export does not return compiled artifact payloads. It does not export the entire historical legacy version chain.

The export includes draft snapshots, governed revisions, cancellation, and retained lifecycle evidence. It retains original actor attribution and reasons when available. Return 401 or 403 for identity or audit failures, 404 for an unknown policy, or 422 for invalid pagination. Inspect target-specific evidence separately. An audit record does not certify activation.