Policy Application Programming Interface on

Authentication and Shared Request Contracts

Mon, 01 Jan 0001 00:00:00 +0000

Call the Policy application programming interface (API) through your authenticated gateway. The gateway establishes identity and trusted authorities. Do not expose the backend directly or supply identity-forwarding headers yourself. Policy derives audit actors from the authenticated principal. Never send submittedBy, approvedBy, or an impersonated username in mutation bodies.

Authentication Model

The public API uses the stable /pty/policy/v1.0 path. That path does not track the Policy application build version. Use your deployment’s configured external root when it differs. Helm uses apiService.rootPath. Standalone deployments use SERVER_ROOT_PATH.

Policy API Operation Directory

Mon, 01 Jan 0001 00:00:00 +0000

The Policy application programming interface (API) uses the stable /pty/policy/v1.0 base path, independently of the application build version. Configure POLICY_API for your gateway through the authentication reference.

Paths identify policies independently of their draft cycles and saved snapshots. Check each operation’s required capability, resource grant, and validator before calling it. A successful lifecycle command can accept asynchronous work without completing target delivery.

Choose an Operation Family

Choose the API reference that matches the operation you need:

Save, Review, Approve, and Inspect Delivery

Mon, 01 Jan 0001 00:00:00 +0000

This application programming interface (API) example follows one Data policy. The author saves and submits. Another authorized user reviews and approves. An authorized auditor then inspects delivery. Separate accounts demonstrate a handoff, not mandatory two-person enforcement.

Before You Begin

Prepare the following before running requests:

Use Bash, curl, jq, and a writable local working directory.
Read authentication and authority.
Give the author policy:edit. Creation supplies its owner grant.
Give the reviewing account policy:review and policy:approve through approved mappings.
Give the auditor policy:audit for delivery inspection.
Prepare working discovery, identity, and Policy Integration Manager (PIM) integrations.
Select a supported Data classification, principal, and discovered resource.

Do not grant broad administrator access just to copy this example. Use your deployment’s existing, approved authority assignments. Do not share tokens between participants. The selected principal receives null-read permission, not cleartext access. Follow your organization’s review rules before running mutations.

Application Programming Interface Errors and Safe Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Interpret errors within the operation’s application programming interface (API) contract. The same status can describe different resources and corrective actions. Interpret Hypertext Transfer Protocol (HTTP) statuses alongside the response body. Retain the method, path, status, safe response body, and timestamp. Keep credentials and sensitive request values out of escalation evidence.

Common HTTP Status Codes

Use this table to interpret common HTTP status codes and identify a response:

Status	Meaning and Response
`304`	Reuse the cached consumer payload when its validator matches. Treat this as successful conditional retrieval.
`400`	Correct malformed parameters or the wrong validator type before repeating the request.
`401`	Authenticate through the gateway with your own valid token.
`403`	Obtain the operation’s capability or required policy grant through approved access management.
`404`	Check the operation-specific absence meaning. Do not assume every response proves a missing policy.
`409`	Read the error message. Reload the draft before editing, the operation list before delivery retry, or ownership inspection before reconciliation.
`412`	Repeat the read that supplied the `ETag`. Compare the updated content before preparing a request with the new validator.
`422`	Correct schema violations or validation findings. Preserve the support reference when present.
`428`	Read the correct resource and supply its required conditional header.
`500`	Save the error and request time. Check policy detail and history to determine whether the command completed before retrying.
`502`	Send the returned deployment error and policy identifier to the Policy Integration Manager (PIM) administrator to check for partial changes.
`503`	Ask the administrator of the named integration to restore access. A failed PIM inventory request does not mean its objects are absent.

For draft commands, a non-draft token normally produces 400. A stale draft token normally produces 409, not uniformly 412. Archive uses the policy token. Reconciliation uses the ownership-registry token. Refer to conditional requests.

Service and Schema Publication Operations

Mon, 01 Jan 0001 00:00:00 +0000

Use the configured POLICY_API base and protected POLICY_AUTH_HEADER file from authentication. All paths below are relative to that base. Examples read the bearer header from that file. Keep request payloads and logs free of credentials. Consult your deployed /doc document for complete nested schemas. Response examples illustrate relevant fields rather than every optional property.

These application programming interface (API) reads return direct payloads. Most reads return 200. Readiness and liveness return empty 204 responses. Gateway access rules can still return 401 or 403. Backend health reads do not independently certify target activation or worker completion.

Catalog, Compilation, and Preview Operations

Mon, 01 Jan 0001 00:00:00 +0000

These application programming interface (API) operations do not save or approve policies. Catalog reads expose discovered vocabulary. Compilation and preview evaluate supplied intent. Require policy:compile for compilation and policy:preview for native preview. Successful operations return 200. For commands using request.json, prepare the complete compile body before running curl. The worked payload construction shows how to build a bounded compileRequest from current catalog identifiers. For compilation or PIM preview, save that nested object’s contents as request.json, without the outer create-policy fields. Policy Integration Manager (PIM) supplies the native Data target.

Policy Queries and Draft Operations

Mon, 01 Jan 0001 00:00:00 +0000

These application programming interface (API) operations inspect and save policy work. Use POLICY_API and the protected POLICY_AUTH_HEADER file from authentication. Saved drafts, governed revisions, and protection states remain independent. Response examples show relevant fields, not every optional property.

Use the policy identifier in {policy_id} paths, including draft commands. Set POLICY_ID to that identifier before running examples for an existing policy. The separate draftPolicyId identifies the stable Draft Policy, not a replacement path identifier. The draft summary’s cycleNumber identifies its authoring cycle. Each save records a draft snapshot. Repeated saves do not create new proposed major revisions. Approval establishes a governed revision. A compilation minor identifies output within that approved revision. Neither snapshot identifiers nor revision numbers replace server-issued validators.

Submission, Review, Approval, and Archive Operations

Mon, 01 Jan 0001 00:00:00 +0000

These application programming interface (API) commands govern saved policy work. Use the POLICY_API base and protected POLICY_AUTH_HEADER file from authentication. Every operation takes a required policy_id path string and no query parameters. Bodies use application/json and reject unknown fields.

Policy derives all actors from trusted identity. Do not send submittedBy, approvedBy, or an archiver identity in a body. Separate-user examples do not imply mandatory two-person enforcement.

A saved snapshot records proposal content at a particular draft head. Submission puts that head into review. It does not establish a governed revision. Approval creates the governed revision and queues separate publication work. Use the policy identifier in every {policy_id} path, not draftPolicyId or a snapshot identifier. Set POLICY_ID to that policy identifier. Before each draft command, read the current draft and retain its exact Draft-ETag as DRAFT_ETAG. For review decisions, use the submitted head you actually reviewed, not a pre-submission token. For archive, retain the current policy ETag as POLICY_ETAG instead.

History and Policy Access Operations

Mon, 01 Jan 0001 00:00:00 +0000

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.

Product Retrieval and Compatibility Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Approval queues asynchronous governed publication. Consumer retrieval, publication, and target activation establish different evidence. Use the application programming interface (API) base and protected POLICY_AUTH_HEADER file from authentication.

Publication makes compiled output available to its target. Consumer receipt records retrieval. Activation means the target uses that output. Approval alone establishes none of these completion conditions.

GET /product-policies/{product_type}

Retrieve the latest published Federated Guardrails aggregate. The current public product_type enum accepts only federated-guardrails. Do not substitute pim or securequery. Accept no body. Optional environment and product_id query strings are reserved and currently ignored. They do not select separate consumer output.

Authoring Schema Operations

Mon, 01 Jan 0001 00:00:00 +0000

These application programming interface (API) reads return 200 with schema vocabulary. They accept no request body and do not save or approve a policy. Gateway access rules apply. These reads do not require a separate command capability. Policy Integration Manager (PIM) owns the Data target vocabulary.

Recovery and Ownership Reconciliation

Mon, 01 Jan 0001 00:00:00 +0000

These application programming interface (API) operations support authorized recovery. They do not replace authoring, review, or target-specific protection checks. Policy Integration Manager (PIM) ownership mappings connect reference keys to native unique identifiers (UIDs). A saved mapping does not prove that its native resource still exists.

Use the POLICY_API base and protected POLICY_AUTH_HEADER file from authentication. Every path below is relative to POLICY_API. Set POLICY_ID to the affected policy identifier for policy-specific requests. For retry, obtain DEPLOYMENT_ID from the operation-list response. For reconciliation, copy identifiers and versions from the inspection response before constructing a decision body.