Policy

• 1: Introduction to Policy
• 1.1: Prepare Access and Example Inputs
• 2: Policy Architecture
• 3: Install
• 3.1: Prerequisites
• 3.1.1: Installation Accounts and Permissions
• 3.2: Installing Policy
• 3.3: Creating Policy Users
• 4: Configure Policy
• 4.1: Policy Security Settings
• 5: Back Up and Restore Policy
• 6: Uninstall Policy
• 7: Policy Application Programming Interface
• 7.1: Authentication and Shared Request Contracts
• 7.2: Policy API Operation Directory
• 7.3: Save, Review, Approve, and Inspect Delivery
• 7.4: Application Programming Interface Errors and Safe Recovery
• 7.5: Service and Schema Publication Operations
• 7.6: Catalog, Compilation, and Preview Operations
• 7.7: Policy Queries and Draft Operations
• 7.8: Submission, Review, Approval, and Archive Operations
• 7.9: History and Policy Access Operations
• 7.10: Product Retrieval and Compatibility Deployment
• 7.11: Authoring Schema Operations
• 7.12: Recovery and Ownership Reconciliation
• 8: Work With Policies
• 8.1: Author Data Policies
• 8.1.1: Configure a Data Policy
• 8.1.2: Save and Validate a Data Draft
• 8.2: Author Artificial Intelligence Policies
• 8.2.1: Configure Artificial Intelligence Protection
• 8.2.2: Preview and Save an Artificial Intelligence Draft
• 8.3: Policy Lifecycle and Governance
• 8.3.1: Submit Saved Work for Review
• 8.3.2: Review and Decide on a Submission
• 8.3.3: Correct Returned Work and Resubmit
• 8.3.4: Restore Policy Intent or Retire a Policy
• 8.4: Monitor Delivery and Withdrawal
• 8.4.1: Verify Data Delivery Evidence
• 8.4.2: Verify Federated Guardrails Delivery Evidence
• 8.4.3: Inspect Delivery Issues and Verify Withdrawal
• 8.5: Create and Review Your First Policy
• 8.6: Common Policy Workflows
• 8.7: Policy Working Practices
• 8.8: Policy Use Cases
• 8.9: Inspect and Use the Policy Library
• 8.10: Policy Authoring Procedures
• 8.11: Policy Lifecycle Operations
• 8.12: Policy Integration Flows
• 9: Troubleshoot Policy
• 9.1: Troubleshoot Authoring and Review
• 9.2: Known Issues and Workarounds
• 9.3: Recover Publication and Withdrawal
• 9.4: Reconcile a Policy's Native Ownership
• 9.5: Remove Verified-Stale Ownership Mappings
• 9.6: Troubleshoot Automatic Recompilation
• 9.7: Common Policy Errors
• 9.8: Collect Policy Diagnostics
• 9.9: Recover Policy Safely
• 9.10: Troubleshoot Installation, Identity, and Routing
• 10: Additional Information
• 10.1: Understand Policy
• 10.1.1: Policy Overview
• 10.1.1.1: Role-Based Access Control and Artificial Intelligence Policies
• 10.1.2: States and Revisions
• 10.1.3: Roles and Permissions
• 10.1.4: Classifications, Principals, and Methods
• 10.1.5: Validation and Review Decisions
• 10.1.6: Policy Terminology
• 10.2: System Operations
• 10.2.1: Background Processing and Cadence
• 10.2.2: Automatic Recompilation of Approved Policies
• 10.2.3: Observe and Restart Policy
• 10.3: Policy Frequently Asked Questions

1 - Introduction to Policy

Start with one policy, a known scope, and a clear review responsibility. This path separates preparing a draft from approving and delivering it. Scope means the data locations or runtime consumer that the exercise should affect. Data and artificial intelligence (AI) exercises use different inputs and verification evidence.

Choose a Responsibility

Choose the path for your responsibility:

• Authors prepare authoring capabilities and applicable policy access. Follow your first policy.
• Reviewers and approvers obtain the capability for their decision. Follow lifecycle and governance.
• Platform operators obtain cluster and dependency access. Follow Installation.
• Application developers obtain a gateway token and the configured application programming interface (API) base. Follow the worked API lifecycle.

These are responsibilities, not additional product roles. Refer to roles and permissions before requesting access.

Complete a First Workflow

Follow these steps to get started:

1. Prepare access and example inputs. You have an identified author, reviewer, scope, and verification owner.
2. Refer to states and revisions. You can distinguish saved work, governed content, and delivery evidence.
3. Follow the first-policy journey. You save, submit, and review a draft before checking its target-specific delivery.

After approval, follow delivery verification. Verify the target-specific result instead of treating approval as protection. For permission or validation failures, use Troubleshoot.

1.1 - Prepare Access and Example Inputs

Prepare this checklist before creating a tutorial policy. Use a nonproduction scope that your team permits you to change. Do not use the example to test protection against production data. Identify the exact data locations or runtime consumer before choosing policy inputs.

Before You Begin

Complete these prerequisites:

• Obtain the Policy address from your platform operator.
• Identify whether the exercise uses Data or artificial intelligence (AI) authoring.
• Read roles and permissions.
• Confirm the target integrations required by your release and exercise.

Prepare the Exercise

Prepare the exercise with the people who will perform it:

1. Sign in with the account that will author the policy. The account can open Policy and perform its assigned authoring operations.
2. Ask the platform administrator to verify the required command capabilities. The author can create work and edit policies they own or can access.
3. Identify the reviewer and approver for this exercise. Each person uses their own account with the appropriate decision capabilities.
4. Select an available classification from your environment. For a Data exercise, confirm it resolves to the intended discovered locations.
5. Select the intended principals from the configured catalog. You can explain who should receive each permission. A principal is a runtime subject, such as a directory group, not a Policy reviewer.
6. Confirm the supported protection method or AI permission choices. Your inputs match the authoring lane and target release.
7. Agree who will verify delivery and protection after approval. That person has the necessary target access and diagnostic permissions.

If catalogs are empty, stop and ask an operator to check discovery and integration setup. Do not fabricate classification identifiers or select unrelated production locations. If authoring access fails, resolve the permission problem before saving work.

Record Your Input Choices

The following values illustrate an exercise, not preinstalled catalog objects. Replace them with real values selected from your environment.

The table lists example exercise inputs and what to verify before using each one:

Alex and Morgan are illustrative people, not account names to provision. Do not share tokens or credentials to simulate a role handoff.

Verify Preparation

You can identify the selected scope, principals, method, and review owner. You also know which delivery evidence will count as success. Save these choices with your team’s exercise notes. Do not record access tokens in those notes. If a definition remains unclear, consult the glossary before substituting an unrelated catalog value.

Continue with the Quickstart. For installation work, start with Installation.

2 - Policy Architecture

Policy separates user-facing governance from asynchronous delivery and target observation. Its web interface and application programming interface (API) share the same backend contracts. Traverse supplies classifications and protection observations. Policy Integration Manager (PIM) receives Data policy configuration. Federated Guardrails consumers retrieve their configuration. An artifact is the target-specific output generated from governed policy intent. Delivery transfers that output. Protection evidence describes the target-specific result.

High-Level Block Diagram

PostgreSQL belongs to the Policy stack. The platform gateway and target integrations have their own operational responsibilities.

flowchart TB
    User[Author or reviewer] --> Gateway[Platform gateway and identity]
    Gateway --> Panel[Policy web interface]
    Panel --> Gateway
    subgraph Policy stack
        API[Policy API and background processing]
        DB[(PostgreSQL)]
        API --> DB
    end
    Gateway --> API
    API -->|Read discovery and protection observations| Traverse
    API -->|Publish native policy work| PIM[Policy Workbench]
    Consumer[Federated Guardrails consumer] -->|Retrieve product policy through gateway| Gateway

Federated Guardrails retrieves its product policy through the supported consumer route. Do not interpret the diagram as a push into every runtime replica. The external artificial intelligence (AI) runtime belongs to its own deployment.

Block Diagram Terms

The following table defines the components and responsibilities shown in the diagram:

Policy Workflow

The author selects scope, principals, and supported protection inputs. Saving retains proposed work. Submission hands its current snapshot to review. An authorized approver creates a governed revision and queues publication. Background processing then delivers artifacts and collects the relevant evidence.

Automatic recompilation can refresh artifacts from approved intent when context changes. It preserves approval identity and does not replace an author’s open draft. Refer to System operations.

Governance and Recovery Boundaries

The local database records Policy governance and delivery state. Restoring this database does not undo changes already made in PIM or configuration already retrieved by Guardrails. Before resuming publication, the platform and integration administrators must compare restored records with the configuration in those products.

A retry continues retained deployment work. Ownership reconciliation addresses native identity and binding decisions. Native means an object in the target product, rather than Policy’s own governance record. A binding associates a Policy reference with that object’s identifier. Neither operation substitutes for reviewing newly authored policy content. Refer to recovery playbooks.

3 - Install

This procedure installs Policy on a Protegrity Provisioned Cluster (PPC). Complete the prerequisites first. The PPC service users and local credential files must be ready before you continue. The chart installs the application programming interface (API), published Policy Panel image, and in-stack PostgreSQL database. It does not install their platform dependencies.

3.1 - Prerequisites

Complete these steps before installing Policy on a Protegrity Provisioned Cluster (PPC). Use a PPC user with administrator permissions to create users and assign roles. This guide calls that user a PPC administrator.

Required Products

Ensure that PPC, Policy Workbench, and Traverse are installed. Ensure that Policy Integration Manager (PIM) is initialized through the Workbench setup. Use the Workbench installation instructions for Amazon Web Services (AWS) or Microsoft Azure.

• Traverse is installed
• Traverse is not installed

If you configured directory connections before installing Policy, save those connection details again after Policy installation. See the IdP backfill issue for the identity provider (IdP) connection steps.

Connect to PPC

Use the Kubernetes connection established during PPC installation. Run the Bash examples in a terminal with Helm, kubectl, jq, and OpenSSL available. All installation commands use the active Kubernetes context:

kubectl config current-context

The output should identify your PPC cluster. For connection instructions, refer to your PPC installation documentation.

PPC Storage and Release Defaults

Policy uses the shared pty-main gateway in api-gateway and the nfa-config ConfigMap in default. These are PPC platform resources, not values you need to supply for a standard installation.

The chart uses PPC’s STORAGE_CLASS and BACKUP_STORAGE_CLASS settings. It creates separate persistent volume claims for the database and logical backups, each requesting 10Gi. It also configures the database accounts and permissions. You do not need to create storage classes, volumes, or database grants manually.

The installation command selects chart version 1.1.0. The chart supplies its application and database image versions and reads the workload registry from PPC. You only need the Open Container Initiative (OCI) chart-registry host from your release distribution. The installation procedure checks whether PPC requires an image-pull Secret and, if so, copies it into the Policy namespace.
For more information about provisioning registry pull secret, refer to Provision the Registry Pull Secret.

Create PPC Service Users

Helm creates database users, but it does not create PPC integration users. Create the two service users once during preparation:

1. Log in to the PPC command-line interface (CLI) as a PPC administrator. Follow Accessing the PPC CLI to connect and sign in to the CLI Manager.

2. Create the token-login role if it does not already exist:

   admin create roles --name policy_service_login --permissions "can_create_token"
   

3. Create the PIM service user:

   admin create users --username pmx.pim.service --roles "workbench_administrator,policy_service_login" --password "<pim-service-password>"
   

4. Create the Traverse service user:

   admin create users --username pmx.traverse.poller --roles "discoverx-automation-client,discoverx-admin,policy_service_login" --password "<traverse-service-password>"
   

   Replace the password placeholders with separate passwords that satisfy PPC’s password policy. Run credential-setting commands in a protected CLI Manager session without command recording. If PPC prompts for a first-login password change, use the final password in the files below.

5. List PPC users:

   admin list users
   

   The output includes the usernames and identifiers of the users you created. Roles are assigned during creation, so no separate user-identifier lookup or role-update command is required.

These users authenticate Policy’s background connections to PIM and Traverse. Policy obtains and refreshes their tokens using the credentials you provide. They are separate from the named PPC accounts people use to sign in. See accounts and permissions for the permission reference.

Prepare Credential Files

Return to the Bash terminal you will use for Helm installation. This guide stores local credential files under the following directory:

$HOME/.config/protegrity/policy/credentials

These are files you create, not preinstalled PPC files. The installation commands below use this location directly. Keep the directory private and outside source control.

Database Credentials

Run this block once to create three database usernames and generate their passwords:

(
  set -e
  set +x
  set -o noclobber
  umask 077
  mkdir -p "$HOME/.config/protegrity/policy/credentials"
  chmod 700 "$HOME/.config/protegrity/policy/credentials"
  for role in maintenance runtime backup; do
    printf '%s' "policy_${role}" > "$HOME/.config/protegrity/policy/credentials/${role}-username"
    password=$(openssl rand -base64 32)
    printf '%s' "$password" > "$HOME/.config/protegrity/policy/credentials/${role}-password"
  done
)

The block creates six files and refuses to overwrite existing files. Helm uses these credentials to create the database logins and their grants. Database provisioning automatically creates pmx_app, a PostgreSQL NOLOGIN permission role, and grants it to runtime. You do not create or validate these database accounts yourself.

PPC Service Credentials

Save the passwords you assigned to the PPC service users:

(
  set -e
  set +x
  set -o noclobber
  umask 077
  printf '%s' 'pmx.pim.service' > "$HOME/.config/protegrity/policy/credentials/pim-username"
  printf '%s' 'pmx.traverse.poller' > "$HOME/.config/protegrity/policy/credentials/traverse-username"
  for service in pim traverse; do
    read -r -s -p "Password for the ${service} service user: " password
    printf '\n'
    if [ -z "$password" ]; then
      printf 'A service-user password is required.\n' >&2
      exit 1
    fi
    printf '%s' "$password" > "$HOME/.config/protegrity/policy/credentials/${service}-password"
  done
)

The prompts hide each password. Use the existing PPC passwords. Do not generate replacements for these users.

Additional Prerequisites

Use the same Bash terminal and active Kubernetes context as the prerequisite steps. These instructions install a new Policy deployment. Set the Open Container Initiative (OCI) chart-registry host supplied with your release:

export POLICY_REGISTRY_HOST='<oci-registry-host>'

Replace the placeholder with the host, including a port if required. The following command installs chart version 1.1.0. Its other settings use PPC defaults. If the chart registry requires authentication, log in:

helm registry login "$POLICY_REGISTRY_HOST"

Helm prompts for registry credentials. The chart registry can differ from PPC’s workload-image registry.
This login authenticates Helm only. It does not authorize cluster nodes to pull workload images. For more information, refer to Provision the Registry Pull Secret.

Continue to Installation

Continue to install the Policy Helm chart.
For more information about installing Policy, refer to section Installing Policy. The procedure creates Kubernetes Secrets from these files and installs Policy with the standard PPC defaults.

3.1.1 - Installation Accounts and Permissions

Policy uses separate database logins, dependency users, and Kubernetes workload identities. These accounts serve different purposes and cannot replace one another. Protegrity Provisioned Cluster (PPC) administrators prepare dependency users before installation. Database operators prepare credentials for PostgreSQL inside the Policy stack.

Use this reference with installation preparation and fresh installation. Default Secret names below apply in the pty-policy release namespace. Use your configured names when the release overrides them.

Database Accounts

The chart defines default Secret names, but no default database usernames or passwords. Choose three distinct login names and independently managed passwords. The example usernames below are suggestions, not chart defaults. Each Secret contains postgres_user and postgres_password. The default database name is policy. Database provisioning also creates the fixed PostgreSQL pmx_app permission role and grants it to runtime. This NOLOGIN role is not a fourth login, platform user, or credential Secret.

The following table lists the database accounts, their permissions, and default Secrets:

Database startup creates missing workload roles from these credentials. The separate bootstrap Job installs the schema and application grants. Operators supply the Secrets. The chart handles account creation and permission checks. No manual database grants or account-validation steps are required. Do not create platform users for these PostgreSQL logins.

The chart creates all three logins without SUPERUSER, CREATEDB, CREATEROLE, REPLICATION, or BYPASSRLS. Maintenance owns objects within the Policy database, not the PostgreSQL cluster. Never use its credentials for ordinary application programming interface (API) traffic. Runtime and backup do not own application objects or assume administrator roles.

Runtime and Backup Privileges

This section explains the database permissions that installation configures automatically. Use it to understand the account separation or investigate a database privilege-check failure. It does not require additional account creation or manual permission grants.

The Policy API uses the runtime database login, such as policy_runtime, to read and update application data. Backup Jobs use a separate login, such as policy_backup, to read data for database dumps. The backup login does not need write access.

PostgreSQL roles can group permissions without serving as login accounts. Policy uses the fixed pmx_app role to group its restricted application permissions. Database provisioning creates this role and assigns membership to the runtime login. Membership lets that login use the role’s permissions. The bootstrap Job configures the grants listed below.

The NOLOGIN setting prevents direct sign-in as pmx_app. This role needs no password or Kubernetes Secret. Installation keeps the backup login outside this role so that it cannot inherit application write permissions. Supply credentials only for the maintenance, runtime, and backup logins described above.

The table compares the resulting permissions of the runtime and backup logins:

Runtime does not have unrestricted create, read, update, and delete access. Its grants preserve protected history while allowing necessary application operations. An allowlist means explicit grants on selected tables or columns, rather than a blanket write grant. For protected records, permitted updates include draft closure, revision supersession, and access-grant revocation metadata. They do not permit rewriting saved authored snapshots.

The derived and compatibility tables with insert, update, and delete grants are:

• policy_versions, policy_decisions, policy_statements, policy_element_refs, and policy_artifacts.
• product_policies, securequery_profiles, securequery_profile_revisions, securequery_capability_manifests, and harmonization_identity.

Bootstrap checks effective privileges, including inherited access. Extra role memberships or public grants can cause startup checks to fail. Do not add broad grants to bypass a failed check.

The postgres identity remains a separate local administration account. Database provisioning clears its network password. Do not expose it or supply it to application workloads.

Naming, Retained Storage, and Rotation

Choose nonempty, distinct usernames of at most 63 bytes. Do not use postgres, pmx_app, or the reserved pg_ prefix. Usernames and passwords must not contain control characters.

Keep the same usernames when reusing database storage. Provisioning rejects changes to the recorded workload names. Changing a Secret name does not migrate database ownership or split a legacy login. Ask the database administrator for a tested ownership-migration procedure before converting an existing database.

Coordinate password rotation across database provisioning and affected workloads. A Secret update alone does not update an existing PostgreSQL password or running environment. Preserve the current credentials and recovery evidence until verification succeeds. Follow configuration changes and backup and restore boundaries.

Dependency Service Users

Create two dedicated regular users in PPC. The following usernames are the documented installation convention. Helm does not create these users or enforce their names. The username in each Secret must match the actual provisioned account. Retain the compatibility identifiers exactly as shown when using this convention.

The following table lists integration users and their required access:

Each dependency Secret contains username and password. Policy supplies these values through the corresponding PIM_* or TRAVERSE_* environment. Both integrations default to the /pty/v1/auth/login/token endpoint. Token login accepts form fields named loginname and password. A successful check returns Hypertext Transfer Protocol (HTTP) 200 and a nonempty pty_access_jwt_token response header. Never print or retain that header in shared logs.

Shared Token-Login Role

The platform administrator creates policy_service_login before installing Policy. Its exact permission set contains only can_create_token. This permission permits token creation and refresh, not dependency access. Keep the role assigned after installation.

Manage this custom role outside the Policy chart’s product configuration. Dependency users do not need the human policy_viewer, policy_author, or policy_admin roles. Do not modify those chart-managed roles to obtain service login. Confirm custom-role support and effective access on the selected platform release.

PIM Permissions and Caller Attribution

The documented workbench_administrator role supplies these permissions:

This bundle grants broader access than a read-only inventory account. workbench_viewer supplies workbench_management_policy_read, not the required writes. Do not substitute that role merely because inventory reads or token login succeed. Before narrowing this mapping, ask the PIM administrator to test inventory reads, publication, and withdrawal with the replacement permissions. See Workbench roles and permissions.

Inventory reads, startup import, and background publication or withdrawal use the service user. Request-driven PIM mutations instead use the calling human’s forwarded token. That human needs their own Workbench permissions for the requested operation. Policy does not silently substitute the worker account after caller authorization fails.

Traverse Permissions and Visibility

The following table summarizes the Traverse roles and their permissions:

Traverse administrator access does not include the automation role’s state-write permission. Keep both dependency roles. Without administrator visibility, login can succeed while the datastore list remains empty. The current integration therefore retains a broad administrator compatibility requirement. Do not share this account with human users or unrelated workloads. Keep both roles until the Traverse integration supports narrower permissions for these operations.

Every Traverse interaction uses the service user, not a human’s forwarded token. Existing installations can use the legacy pmx.discoverx.poller username. Use its actual verified credentials rather than renaming a working account during installation.

Kubernetes and Directory Identities

Kubernetes ServiceAccounts are not PPC users or PostgreSQL logins. The chart creates policy-api, policy-panel, and policy-db by default. They follow the corresponding workload containerName settings. The chart disables service-account token automount for these identities.

Traverse also uses a scanner ServiceAccount for shared identity provider (IdP) metadata. The default scanner is discoverx-discoverx-scanner in the discoverx namespace. Configure idpSecret.writer for the actual scanner identity in your deployment. Policy grants that identity only patch on the named discoverx-idp-connections Secret in the Policy namespace. It does not grant general Secret read, list, create, or delete access. This Kubernetes permission does not replace the poller’s Traverse roles.

Directory bind and provider credentials remain separate, source-specific identities. Policy defines no default directory bind username. Do not reuse database or dependency service passwords for directory access. Registry pull credentials likewise remain platform-owned.

3.2 - Installing Policy

This section describes the steps to install and verify Policy. Ensure that all the prerequisites for installation have been met.
For more information about the prerequisites, refer to Prerequisites.

Create the Namespace

Create the Policy namespace:

kubectl create namespace pty-policy

Continue to Provision the Registry Pull Secret.

Provision the Registry Pull Secret

Policy workload images are downloaded from the PPC workload-image registry. This can differ from the chart registry you logged in to with helm registry login. This login enables Helm to download the chart. It does not let the cluster nodes pull images. If the Secret is needed and missing, then the pods fail with ErrImagePull or ImagePullBackOff.

Perform the following steps to provision the registry pull secret:

1. Read the Secret name configured by PPC:

export REGISTRY_SECRET_NAME="$(kubectl --namespace default get configmap nfa-config \
  -o jsonpath='{.data.REGISTRY_SECRET_NAME}')"
echo "REGISTRY_SECRET_NAME=${REGISTRY_SECRET_NAME:-<empty>}"

If the value is empty, the nodes authenticate to the registry themselves. Skip to Database Credentials.
For more information refer to Database Credentials.

2. If the value is set, copy the Secret into the Policy namespace. Replace default if your PPC platform namespace differs.

kubectl --namespace default get secret "$REGISTRY_SECRET_NAME" -o json \
  | jq -c '{apiVersion, kind, type, data, metadata: {name: .metadata.name, namespace: "pty-policy"}}' \
  | kubectl create -f -

If the command reports AlreadyExists, do not overwrite the Secret. Verify it in the next step.

3. Verify the Secret:

kubectl --namespace pty-policy get secret "$REGISTRY_SECRET_NAME"

The TYPE must be kubernetes.io/dockerconfigjson. Resolve any error before continuing.

The chart references only the Secret’s name and never reads or copies its data through Helm. The copy is not synchronized. When the platform Secret is renewed or replaced, update the copy in pty-policy.

Database Credentials

Create the three database Secrets from the files prepared in prerequisites:

(
  set -e
  for role in maintenance runtime backup; do
    kubectl --namespace pty-policy create secret generic "policy-db-${role}" \
      --from-file="postgres_user=$HOME/.config/protegrity/policy/credentials/${role}-username" \
      --from-file="postgres_password=$HOME/.config/protegrity/policy/credentials/${role}-password"
  done
)

The commands create policy-db-maintenance, policy-db-runtime, and policy-db-backup. They read passwords from the protected files without printing them. For managed credential delivery instead, see credential handling.

PPC Service Credentials

Create the integration Secrets from the prepared PPC user credentials:

(
  set -e
  for service in pim traverse; do
    kubectl --namespace pty-policy create secret generic "${service}-credentials" \
      --from-file="username=$HOME/.config/protegrity/policy/credentials/${service}-username" \
      --from-file="password=$HOME/.config/protegrity/policy/credentials/${service}-password"
  done
)

The commands create pim-credentials and traverse-credentials. Policy uses these users to obtain and refresh dependency access tokens.

Install the Chart

Run the following command:

helm install policy "oci://${POLICY_REGISTRY_HOST}/policy/helm/policy" \
  --version 1.1.0 \
  --namespace pty-policy \
  --wait --wait-for-jobs --timeout 15m

The standard installation does not require a separate values file. For nondefault settings, append --values customer-values.yaml with your configuration file. See configuration for supported overrides.

The chart automatically:

• Deploys the Policy API, Panel, and in-stack PostgreSQL.
• Creates the database logins from the supplied credentials.
• Configures pmx_app membership and database permissions.
• Initializes the application schema through the bootstrap Job.
• Registers the built-in Policy roles and gateway authorization resources.
• Creates storage claims using PPC’s configured storage classes.
• Configures startup, readiness, and liveness probes.

Database provisioning automatically creates pmx_app, a PostgreSQL NOLOGIN permission role, and grants it to runtime. The wait options keep Helm running until workloads and bootstrap Jobs are ready. You do not need to inspect database grants, repeat health probes, or recheck chart-created roles.

If Helm fails, use installation troubleshooting. Keep the credential files until installation completes and you store the credentials through your normal secret-management process.

After Helm completes, follow Creating Policy users to create or assign the named PPC account that will sign in. The chart registers the built-in roles. You assign them to people separately.

Verifying the Installation

Helm waits for workloads and database bootstrap through the command’s wait options. No separate installer checks of database grants, built-in roles, or health probes are required. Complete these steps with your assigned PPC account:

1. Get the Policy web address from PPC:

   kubectl --namespace default get configmap nfa-config \
     -o jsonpath='https://{.data.FQDN}/pty/policy/v1.0/ui/{"\n"}'
   

   The command uses the PPC cluster’s fully qualified domain name (FQDN). Use your configured path if your installation overrides the default.

2. Open that address in your browser and sign in with your named PPC account.

3. Open the Policy Library.

   The Library displays the policies you can access. An empty list is normal before anyone creates a policy.

If you cannot open Policy or sign in, use installation and access troubleshooting.

If you configured Traverse directory connections before installing Policy, the connection owner may need to save those details again. See the identity provider (IdP) backfill issue.

3.3 - Creating Policy Users

People sign in to Policy with named Protegrity Provisioned Cluster (PPC) accounts. The Policy Helm chart registers the built-in roles during installation. A PPC user with administrator permissions assigns these roles to people. Human accounts are separate from the integration service users prepared in prerequisites.

Prerequisites

Complete Policy installation before assigning its chart-created roles. Use a PPC account with administrator permissions to manage users.

Policy Roles

Choose the role required for the person’s tasks:

Use the authorization reference for capability details and policy-specific grants. Do not grant administrative access merely to provide author or read-only access.

Create a Policy User

Complete these steps in the PPC command-line interface (CLI):

1. Log in to the PPC CLI as a PPC user with administrator permissions. See Accessing the PPC CLI.

2. Create an author account:

   admin create users --username <username> --email <email> --first-name <first-name> --last-name <last-name> --password "<password>" --roles "policy_author"
   

   Replace the placeholders with the person’s account details. Run credential-setting commands in a protected CLI Manager session without command recording. For read-only access, use policy_viewer instead of policy_author.

3. List PPC users:

   admin list users
   

   The output includes the account you created.

For an existing user, follow PPC user management. Include every role the account must retain when changing its roles. Updating a user’s roles replaces the existing role list.

4 - Configure Policy

Platform operators configure Policy through the selected chart and approved secret management. Protegrity Provisioned Cluster (PPC) administrators control human and dependency access. Use nonsecret customer values to record deployment choices reproducibly. A chart value controls generated Kubernetes resources. An environment variable configures the running backend process. A credential Secret supplies sensitive values. Changing one does not automatically change the underlying account.

Choose a Reference

Choose the reference that matches the setting:

• Refer to Security settings to distinguish human capabilities, resource grants, worker credentials, network access, and signing keys.
• Refer to installation prerequisites for required platform and identity inputs.

Apply a Configuration Change

Apply a reviewed change through the release configuration:

1. Identify the owner and impact of the setting. Record whether it changes credentials, storage, schema, scheduling, or target access.
2. Compare your current release values with the selected chart defaults. Do not assume a new default overrides an existing explicit value.
3. Update your reviewed nonsecret override file. Keep passwords, tokens, and private keys in approved secret management.
4. Ask the platform and database administrators to confirm the procedure, downtime, and recovery plan before applying another chart revision.
5. Repeat installation verification. Refer to installation verification. Confirm effective settings through system operation. Refer to System operations.

Do not edit generated ConfigMaps as a lasting configuration method. Helm can overwrite those edits, and existing processes may retain old values. A healthy rollout does not establish correct downstream identity or protection.

For ongoing work, refer to background processing and automatic recompilation.

4.1 - Policy Security Settings

Policy separates authenticated users, command capabilities, resource grants, and integration identities. Each controls a different boundary. Successful network access does not establish permission to approve or repair policies. The application programming interface (API) and Policy Integration Manager (PIM) also enforce different authority boundaries.

Security Controls

The chart uses non-root workloads, restricted container contexts, dropped Linux capabilities, and read-only filesystems where applicable. It disables privilege escalation and limits network paths. These settings do not replace gateway authentication or cluster network enforcement.

Keep local mode and fake dependencies disabled in customer deployments. Keep certificate verification enabled with the correct trust material. Do not treat authentication failures as reasons to bypass the gateway.

Roles and Authorization

With authorization.enabled: true, the chart registers human application roles and gateway authorization resources. Policy derives actors from trusted platform identity. Callers must not forge identity headers or send another user’s audit identity. The following table summarizes each built-in role and its authority boundary:

Reviewer and approver describe responsibilities, not a fictional reviewer role. Different authenticated people can author, review, and approve. Policy command checks do not themselves require different people. Apply your deployment’s approved separation-of-duties requirements. Never share credentials to demonstrate a handoff.

Use this table to match common tasks with their required command authority:

Owner/editor grants do not supply review or approval capability. Author capability alone does not permit reviewer decisions. Audit read access does not authorize recovery mutations. Do not grant the broad administrator role merely to satisfy one task. Identity owners assign the chart-registered roles to the appropriate human accounts.

Gateway policy-library-read, policy-library-edit, and policy-library-admin permissions map to different capability bundles. The Library administrator permission does not include every system or observability permission. Unknown authorities grant no capability. Refer to roles and permissions and API authentication for shared contracts.

Consumer Evidence

The empty-string default for GUARDRAILS_CONSUMER_USERNAME accepts anonymous-only pull evidence. Only requests with absent or empty identity qualify in this compatibility mode. Named requests do not qualify under the empty-string default. A nonempty value permits receipts only for an exact gateway-verified service username. Qualifying 200 and 304 retrievals can both record receipts. With a nonempty setting, anonymous reads and diagnostics under another identity do not qualify. A matching receipt does not prove Federated Guardrails activation. A receipt records a qualifying read of a particular product artifact. Activation means the consumer actually applies that configuration. Read evidence alone cannot establish it.

The setting does not authenticate that user. The gateway must validate identity and reject caller-supplied identity headers. Network policies alone cannot establish trusted identity. Keep the Guardrails consumer’s credentials separate from human, PIM, and Traverse credentials.

The chart maps apiService.environment.GUARDRAILS_CONSUMER_USERNAME through the API ConfigMap into the environment.

Credential Handling

Keep the following credentials separate. Database usernames below are examples, not defaults. Dependency usernames are documented conventions.

The following table summarizes credential identities and their boundaries:

pmx_app is an automatically created PostgreSQL NOLOGIN permission role, not a credentialed account. The database reference defines its grants and the runtime/backup boundary. For database and service credential Secret names and keys, refer to the installation steps for database credentials and PPC service credentials. For exact account names, dependency roles, database grants, and Kubernetes identities, refer to accounts and permissions. Do not store secrets in values files, --set arguments, tickets, or log excerpts. Treat logs and diagnostics as sensitive even where credential redaction applies.

The platform-owned login-only policy_service_login role contains can_create_token. Combine it with the dependency’s required access. Do not modify chart-managed human roles to obtain worker login. PIM background publication and withdrawal need policy-write access. Read-only Workbench permission is insufficient. Grant only the required dependency access through approved mappings.

The documented PIM account uses workbench_administrator plus policy_service_login. The documented Traverse account uses discoverx-automation-client, discoverx-admin, and policy_service_login. Traverse administrator visibility does not grant the automation role’s state writes. Its current administrator requirement is a compatibility exception, not a read-only role. Do not replace either assignment with a guessed least-privilege bundle.

A Policy administrator role does not grant Workbench permission to a human. Interactive PIM mutations require the caller’s forwarded credential and dependency authority. They do not silently fall back to the worker account. Platform account changes do not automatically update Kubernetes Secrets.

For registry access, the chart references the platform-named Secret already present in the release namespace. It does not create, copy, or rotate it. Coordinate renewal with the platform owner. For managed database credentials, inspect external secret reconciliation and deletion policies before rotating or removing anything. Changing a Secret alone does not necessarily change an existing database login.

External Resources After Uninstallation

Helm removal does not revoke external accounts or erase every backup. The uninstallation procedure separates retained-data removal from irreversible cleanup. Use these ownership boundaries when preparing that cleanup:

Deleting a Kubernetes Secret does not invalidate its underlying password or token. For final removal, the identity owner disables the dedicated PIM and Traverse users and revokes their active tokens through platform administration. Shared users require a dependency review rather than automatic deletion. The secret-provider owner removes obsolete remote credentials and synchronization rules. The change record should identify each owner and their verification result, without secret values. For retained-data recovery, required database identities and usable dependency credentials remain necessary.

Rotate the Policy Signing Key

Policy signs ownership markers on managed PIM objects. This privileged operation changes persisted signing identity and native markers. It is not a routine password rotation. Use an approved change window, recoverable signing state, and working PIM access.

Complete the explicit cluster-context setup in this operator session before running signing commands. Confirm that the reported cluster and selected namespace identify the intended Policy deployment. Stop if either differs from the approved change target.

The packaged operator command supports status, rotate, and re-sign. For an authorized operator, status inspection uses:

kubectl --context "${CTX:?Set CTX}" --namespace pty-policy exec deployment/policy-api \
  --container policy-api -- \
  /app/.venv/bin/python -m pmx.api.signing_key status

The command reports fingerprints, not key material. After approving rotation, use the same command with rotate instead of status. Rotation re-signs managed markers and requires no pod restart. If PIM becomes unavailable, restore access and run re-sign. Inspect status again before declaring completion.

The previous key’s default seven-day grace period starts only after successful re-signing. Markers still needing the previous key can suspend that grace period. The drop-previous command stops accepting the previous key immediately. Reserve it for an approved compromise response. Dependent markers will stop verifying. Do not use it to bypass incomplete re-signing.

Network Policy Integration

The chart provides default-deny policies and selected allow paths. These policies require a container network interface (CNI) that enforces Kubernetes network policies. Gateway routes protect API and Panel access. Health probes access the Service directly and do not prove gateway protection. Direct diagnostic access can bypass gateway authentication.

The apiConsumers list permits selected direct consumers. Each entry must specify a namespace and a nonempty pod selector. Use actual workload labels and set apiConsumers: [] when no direct consumer needs access. Namespace-only consumer access is not a supported replacement. Network reachability does not replace caller authentication and authorization.

Procedure

Refer to configuration workflow for deployment controls. Coordinate role changes with identity owners and credential rotation with dependency owners. Do not print Secret values or assign broad roles as troubleshooting shortcuts.

Chart-Managed Security

The chart configures workload security settings, network policies, and gateway authorization resources. It registers the built-in roles and their permission mappings automatically. Installers do not need to inspect these resources or retest the built-in role boundaries. Platform administrators provide gateway authentication and a CNI that enforces network policies. Protegrity Provisioned Cluster (PPC) users with administrator permissions assign user access and manage external dependency credentials.

5 - Back Up and Restore Policy

Use this procedure as the platform operator and database maintenance owner. Policy keeps PostgreSQL inside its stack. A backup protects Policy’s database, not changes made in other products. Agree on acceptable data loss and a maintenance window before recovery.

Note: Earlier Amazon Web Services (AWS) restore drills used one shared database identity. They do not qualify the current release’s three database identities. Azure evidence covers mocked chart checks only. Engineering or Quality Assurance must qualify these command sequences on your target platform before production use.

Before You Begin

• Use Bash, Helm, kubectl, and jq with access to the intended cluster.
• Install the Velero command-line interface when using Velero snapshots.
• Obtain permission to manage Policy Jobs, workloads, and backup resources.
• Preserve the original maintenance, runtime, and backup usernames and credential Secrets.
• Keep the original chart version, configuration, signing keys, and dependency credentials in protected recovery storage.
• Coordinate other maintenance sessions. Suspending a CronJob does not stop existing Jobs or prevent another operator from creating one.

Run the examples in one dedicated Bash shell. The defaults below match a standard installation; adjust names for custom deployments. Set POLICY_REGISTRY_HOST to the chart registry used during installation. Use the chart version from the installation or recovery record, not a newer release.

set -euo pipefail
set +x
umask 077
CTX="$(kubectl config current-context)"
POLICY_NAMESPACE='pty-policy'
VELERO_NAMESPACE='pty-backup-recovery'
VELERO_SCHEDULE='policy-db-backup'
BACKUP_PVC='policy-db-backup-pvc'
CHART="oci://${POLICY_REGISTRY_HOST:?Set the chart registry host}/policy/helm/policy"
CHART_VERSION='1.1.0'
kubectl --context "$CTX" cluster-info
helm --kube-context "$CTX" list --namespace "$POLICY_NAMESPACE" --filter '^policy$'

Confirm the displayed cluster and installed chart match your recovery plan. Do not continue against another cluster. For disaster recovery, use the protected configuration and credentials from the source installation.

Understand the Backup Boundary

The chart writes a logical Structured Query Language (SQL) dump to a separate persistent volume claim (PVC). The default location is policy-db-backup-pvc, containing pg_dump.sql. It does not contain PostgreSQL’s live data directory. Each successful dump replaces the previous file only after staging succeeds. A failed dump leaves the previous file intact, so file presence does not establish freshness.

Velero snapshots this dump claim, not the complete application or dependency environment. It does not include database credential Secrets or external product state. An older snapshot contains the dump captured then, not an arbitrary point in database history. Without Velero or another approved off-node copy, a retained local dump does not protect against storage loss.

Backup Settings

Record nondefault settings in your protected customer values file. The following settings control dump and snapshot scheduling:

These settings select or configure recovery storage and replay:

Use the protected configuration again when resuming normal operation. The snapshot offset does not guarantee that a dump has finished. Choose schedules, capacity, and retention for your deployment. Changing a storage-class value does not migrate an existing claim. The claim’s Helm retention annotation does not protect against explicit deletion or storage loss.

Check Automatic Backups

Inspect the configured schedules and recent dump Jobs:

kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
  get cronjob policy-db-backup-cronjob
kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" get jobs,pvc
kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" get jobs \
  -l app.kubernetes.io/component=db-backup --sort-by=.metadata.creationTimestamp

In normal mode, expect SUSPEND to show False, the dump claim to show Bound, and recent scheduled Jobs to complete. Select the exact recent Job name from that output:

DUMP_JOB='replace-with-the-recent-job-name'
kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
  get job "$DUMP_JOB" -o json |
  jq '{name: .metadata.name, start: .status.startTime,
       completed: .status.completionTime, conditions: .status.conditions}'
kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" logs job/"$DUMP_JOB" --all-containers=true

Expect a Complete condition with status: "True" and a recent completion time. Investigate a failed Job or an unexpectedly old completion time. An older successful Job does not prove that the latest scheduled dump succeeded.

When Velero is enabled, inspect its Schedule and completed backups:

kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
  get schedules.velero.io "$VELERO_SCHEDULE"
kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" get backups.velero.io \
  -l "velero.io/schedule-name=$VELERO_SCHEDULE" -o json |
  jq -r '.items | sort_by(.status.completionTimestamp // "")[] |
    [.metadata.name, .status.phase, (.status.errors // 0),
     (.status.completionTimestamp // "pending")] | @tsv'

Expect the Schedule to remain unpaused and recent backups to report Completed with zero errors. Correlate the selected snapshot with the preceding successful dump. Do not assume the thirty-minute schedule offset establishes that relationship.

Take a Backup Now

This sequence creates a new logical dump using the chart’s existing CronJob template. It does not create database credentials or run the destructive development test scripts. Run it only in normal mode, with backups enabled and no other maintenance session.

1. Save normal-mode values privately before changing scheduling.

   RECOVERY_DIR="$(mktemp -d "$HOME/.policy-recovery.XXXXXX")"
   NORMAL_VALUES="$RECOVERY_DIR/normal-values.json"
   helm --kube-context "$CTX" get values policy \
     --namespace "$POLICY_NAMESPACE" --all --output json > "$NORMAL_VALUES"
   jq -e '.global.restore == false and .backup.enabled == true' "$NORMAL_VALUES"
   USE_VELERO="$(jq -er '.backup.veleroEnabled | tostring' "$NORMAL_VALUES")"
   

   Expect true from the configuration check. The private values file can contain sensitive configuration. Helm accepts this JSON file through its --values option. Retain it and the exact chart version in approved recovery storage outside the cluster. Do not include it in support logs or source control.

2. Confirm both schedules currently run normally, then pause them.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     get cronjob policy-db-backup-cronjob -o json |
     jq -e '(.spec.suspend // false) == false'
   if [[ "$USE_VELERO" == true ]]; then
     kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
       get schedules.velero.io "$VELERO_SCHEDULE" -o json |
       jq -e '(.spec.paused // false) == false'
   fi
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     patch cronjob policy-db-backup-cronjob --type=merge \
     -p '{"spec":{"suspend":true}}'
   if [[ "$USE_VELERO" == true ]]; then
     kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
       patch schedules.velero.io "$VELERO_SCHEDULE" --type=merge \
       -p '{"spec":{"paused":true}}'
   fi
   

   If a schedule was already paused, stop and identify its maintenance owner. Pausing does not cancel an active dump or snapshot.

3. Wait for existing dump Jobs and Velero backups to finish. Check for nonterminal dump Jobs:

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" get jobs \
     -l app.kubernetes.io/component=db-backup -o json |
     jq -e '[.items[] | select(
       any(.status.conditions[]?;
         (.type == "Complete" or .type == "Failed") and .status == "True") | not
     )] | length == 0'
   

   Expect true before starting another dump. If false, inspect the listed Jobs and wait for them to finish. Also wait for any active Velero backup shown in the previous section. Do not run overlapping dump writers against the shared staging filename.

4. Create and wait for a uniquely named dump Job.

   DUMP_JOB="policy-db-manual-$(date -u +%Y%m%d%H%M%S)"
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" create job "$DUMP_JOB" \
     --from=cronjob/policy-db-backup-cronjob
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     wait --for=condition=complete job/"$DUMP_JOB" --timeout=10m
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     logs job/"$DUMP_JOB" -c policy-db-backup
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" get job "$DUMP_JOB" \
     -o jsonpath='{.metadata.name}{"\t"}{.status.startTime}{"\t"}{.status.completionTime}{"\n"}'
   

   Expect this new Job to complete after its recorded start time. The inherited command replaces pg_dump.sql only after a successful dump. Completion of this exact Job therefore confirms a fresh dump write. Stop if it fails or times out; do not treat the previous file as the requested backup.

5. If Velero is enabled, capture this dump in a named recovery snapshot. Keep dump scheduling paused until the snapshot finishes.

   if [[ "$USE_VELERO" == true ]]; then
     BACKUP_NAME="policy-db-manual-$(date -u +%Y%m%d%H%M%S)"
     velero --kubecontext "$CTX" --namespace "$VELERO_NAMESPACE" \
       backup create "$BACKUP_NAME" --from-schedule "$VELERO_SCHEDULE" --wait
     kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
       get backups.velero.io "$BACKUP_NAME" -o json |
       jq -e '.status.phase == "Completed" and (.status.errors // 0) == 0'
     velero --kubecontext "$CTX" --namespace "$VELERO_NAMESPACE" \
       backup describe "$BACKUP_NAME" --details
   fi
   

   Expect true and review any warnings before accepting the checkpoint. Record the exact backup name and completion time, not just the Schedule name. Without Velero, this procedure creates only the dump on the existing claim.

6. Resume the schedules after the backup succeeds.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     patch cronjob policy-db-backup-cronjob --type=merge \
     -p '{"spec":{"suspend":false}}'
   if [[ "$USE_VELERO" == true ]]; then
     kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
       patch schedules.velero.io "$VELERO_SCHEDULE" --type=merge \
       -p '{"spec":{"paused":false}}'
   fi
   

   Recheck both schedules. If any step fails, inspect the exact Job or backup and notify the maintenance owner. The schedules remain paused until that owner resolves the failure and explicitly resumes them.

Qualify a Backup Checkpoint

Record the dump Job, its completion time, the exact snapshot name, and the chart version. Retain the original values and credential references separately. A completed snapshot alone does not establish application-level recoverability. Rehearse recovery with representative policy revisions and history. Include signing-key recovery and external-product reconciliation in that rehearsal.

Policy signs ownership markers on Policy Integration Manager (PIM) objects. If signing keys changed after the backup, coordinate with the PIM administrator. For information about signing keys, refer to signing keys.

Restore Prerequisites and Stop Conditions

Restore replaces database contents and can discard changes after the selected dump. Use an approved maintenance window and preserve the current database when possible. Keep the original three usernames and matching credentials available. Use the same chart and application versions as the approved recovery record. Do not use database restore to repair an ordinary connectivity or publication failure.

Stop when the dump’s provenance, storage attachment, credentials, or version compatibility is uncertain. Exclude other database clients, including sessions using the maintenance username. The chart’s session check and advisory lock do not exclude every competing maintenance client.

Restore Sequence and Chart Gates

Choose one recovery source:

• Existing dump volume: replay the current file on the retained backup claim.
• Velero backup: recover a named earlier snapshot into a prepared recovery target.

Both paths keep application processing stopped during replay. The chart omits ordinary bootstrap, suspends scheduled dumps, and pauses Velero scheduling in restore mode. It uses the maintenance identity for one transactional SQL replay.

Set NORMAL_VALUES to the protected original JSON values file before choosing either path. Check that it describes normal operation, then read the original Velero setting:

test -s "${NORMAL_VALUES:?Set the protected original values file}"
jq -e '.global.restore == false and .backup.enabled == true' "$NORMAL_VALUES"
USE_VELERO="$(jq -er '.backup.veleroEnabled | tostring' "$NORMAL_VALUES")"

Expect true from the configuration check. Do not use a values file captured after entering restore mode.

Restore from the Existing Dump Volume

Use the NORMAL_VALUES file saved before recovery overrides. For another shell, set it to the full path of that protected file. Confirm the existing claim contains the intended dump; this path cannot select an older file.

1. Stop scheduled dumps and active dump Jobs before stopping the application programming interface (API). Deleting backup Jobs here terminates in-flight dumps, not stored database contents.

   test -s "${NORMAL_VALUES:?Set the protected original values file}"
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     patch cronjob policy-db-backup-cronjob --type=merge \
     -p '{"spec":{"suspend":true}}'
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" delete jobs \
     -l app.kubernetes.io/component=db-backup --cascade=foreground --wait=true
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     scale deployment/policy-api --replicas=0
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     wait --for=delete pod -l app.kubernetes.io/component=api --timeout=5m
   

   Confirm other maintenance clients have stopped. Do not continue if a dump or database client can still write.

2. Enter restore mode using the original values, disabling Velero for this retained-volume path.

   helm --kube-context "$CTX" upgrade policy "$CHART" --version "$CHART_VERSION" \
     --namespace "$POLICY_NAMESPACE" --reset-values --values "$NORMAL_VALUES" \
     --set global.restore=true --set backup.enabled=true --set backup.veleroEnabled=false \
     --wait --wait-for-jobs --timeout 6h
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     logs job/policy-db-restore-job -c policy-db-restore
   

   Expect the restore Job to complete successfully. The six-hour timeout matches the default replay deadline. If Helm fails, inspect the Job and its logs; keep the API stopped. Do not enable automatic rollback or return to normal mode to hide the failure.

3. Continue with verification and resumption.

Recover a Velero Backup

Use an approved recovery target with the same Policy namespace and no existing dump claim. Prepare its platform dependencies, original database Secrets, and protected normal-mode values first. Recovering storage does not recover those credentials. Do not delete an existing claim or uninstall a healthy release to follow this path. If the target contains retained storage, use the retained-storage handoff.

1. Select the exact completed backup from the source cluster’s available recovery storage. Use the list in Check automatic backups. Select the newest completed snapshot for latest recovery, or an approved older snapshot.

   RESTORE_BACKUP='replace-with-the-approved-backup-name'
   kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
     get backups.velero.io "$RESTORE_BACKUP" -o json |
     jq -e '.status.phase == "Completed" and (.status.errors // 0) == 0'
   test -s "${NORMAL_VALUES:?Set the protected original values file}"
   

   Expect true. Record the selected backup and its captured dump time. Do not use a failed backup or assume its name establishes freshness.

2. Create the recovery release with the source values and selected backup.

   helm --kube-context "$CTX" upgrade --install policy "$CHART" --version "$CHART_VERSION" \
     --namespace "$POLICY_NAMESPACE" --create-namespace \
     --reset-values --values "$NORMAL_VALUES" \
     --set global.restore=true --set backup.enabled=true --set backup.veleroEnabled=true \
     --set-string backup.backupName="$RESTORE_BACKUP"
   

   Do not add --wait-for-jobs in this phase. The SQL replay Job intentionally stays suspended until Velero completes recovery. An existing failed or differently selected policy-db-restore needs operator investigation; do not delete it blindly.

3. Wait for Velero, then check its exact source and error count.

   kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
     wait --for=jsonpath='{.status.phase}'=Completed \
     restores.velero.io/policy-db-restore --timeout=4h
   kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
     get restores.velero.io policy-db-restore -o json |
     jq -e --arg backup "$RESTORE_BACKUP" \
       '.spec.backupName == $backup and .status.phase == "Completed" and (.status.errors // 0) == 0'
   

   Expect true. A failed, partial, or mismatched recovery is not safe for SQL replay.

4. Verify the recovered claim and its ownership.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     wait --for=jsonpath='{.status.phase}'=Bound pvc/"$BACKUP_PVC" --timeout=10m
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" get pvc "$BACKUP_PVC" -o json |
     jq -e --arg backup "$RESTORE_BACKUP" --arg ns "$POLICY_NAMESPACE" \
       '.status.phase == "Bound"
        and .metadata.labels["velero.io/backup-name"] == $backup
        and .metadata.labels["velero.io/restore-name"] == "policy-db-restore"
        and .metadata.labels["app.kubernetes.io/backup"] == "policy-db"
        and .metadata.labels["app.kubernetes.io/managed-by"] == "Helm"
        and .metadata.annotations["meta.helm.sh/release-name"] == "policy"
        and .metadata.annotations["meta.helm.sh/release-namespace"] == $ns'
   

   Expect true before allowing replay. For custom backup labels, use the original backup.label settings in this check.

5. Reapply restore mode to release the SQL Job.

   helm --kube-context "$CTX" upgrade policy "$CHART" --version "$CHART_VERSION" \
     --namespace "$POLICY_NAMESPACE" --reuse-values --set global.restore=true \
     --wait --wait-for-jobs --timeout 6h
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     logs job/policy-db-restore-job -c policy-db-restore
   

   Helm checks Velero’s state when rendering; it does not watch for completion automatically. Continue only after SQL replay succeeds.

Verify and Resume Normal Operation

1. Confirm replay completion and inspect restored records before starting the API.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     wait --for=condition=complete job/policy-db-restore-job --timeout=10m
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     exec statefulset/policy-database -c policy-database -- sh -ec \
     'PGHOST=127.0.0.1 PGUSER="$PMX_BACKUP_USER" PGPASSWORD="$PMX_BACKUP_PASSWORD" \
      psql -X --no-password -v ON_ERROR_STOP=1 -d "$POSTGRES_DB" \
      -c "SELECT version_num FROM public.alembic_version;" \
      -c "SELECT count(*) AS policies FROM public.policies;" \
      -c "SELECT count(*) AS revisions FROM public.policy_revisions;" \
      -c "SELECT count(*) AS history_events FROM public.policy_lifecycle_events;"'
   

   Compare the schema and known policy/history records with the recovery record. Counts alone do not prove data fidelity. Keep the API stopped if the result differs unexpectedly.

2. Have the PIM, Traverse, and Guardrails owners reconcile changes made after the backup. Restoring SQL cannot reverse those external effects. Do not resume processing when a restored pending request could repeat or reverse an uncertain external change.

3. Clear manual dump suspension, then restore the original normal-mode configuration.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     patch cronjob policy-db-backup-cronjob --type=merge \
     -p '{"spec":{"suspend":false}}'
   helm --kube-context "$CTX" upgrade policy "$CHART" --version "$CHART_VERSION" \
     --namespace "$POLICY_NAMESPACE" --reset-values --values "$NORMAL_VALUES" \
     --set global.restore=false --wait --wait-for-jobs --timeout 15m
   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     rollout status deployment/policy-api --timeout=5m
   

   The original values restore the original Velero setting. Do not resume with temporary backup.veleroEnabled=false overrides or blindly reuse recovery values. Normal mode reruns bootstrap and runtime checks before admitting the API.

4. Confirm backup scheduling resumed.

   kubectl --context "$CTX" --namespace "$POLICY_NAMESPACE" \
     get cronjob policy-db-backup-cronjob -o json |
     jq -e '.spec.suspend == false'
   if [[ "$USE_VELERO" == true ]]; then
     kubectl --context "$CTX" --namespace "$VELERO_NAMESPACE" \
       get schedules.velero.io "$VELERO_SCHEDULE" -o json |
       jq -e '.spec.paused == false'
   fi
   

   Expect true for each enabled schedule.

5. Sign in with your own Policy account and open Policy Library. Compare known approved versions, drafts, and history with the selected backup. Then repeat Take a backup now to confirm a new dump and, when enabled, a new snapshot complete.

If recovery fails, collect the exact Job or Restore status and logs. Keep restore mode enabled and use the diagnostic handoff. Do not change credentials, delete storage, or restart ordinary processing merely to obtain healthy pods.

Recovery Limits

SQL replay cannot reverse PIM, Traverse, or Guardrails effects after the backup. A restored publication receipt does not prove current runtime protection. Use reconciliation and recovery with the integration owners. Do not infer a supported downgrade or recovery-time guarantee from a successful replay.

Recover after Uninstall

Use this path when uninstallation removed workloads but retained database storage. This is not a fresh installation or a routine release change. A generic reinstall against retained storage is not a qualified customer procedure. Contact your platform/database recovery owner or Protegrity Support before reattaching retained claims. Provide claim identities, original chart and image versions, protected configuration references, and the selected recovery checkpoint. Do not send credential values.

Healthy retained live data may not need SQL replay. Replaying an older dump can discard newer state. Do not run a fresh installation against retained storage or regenerate its credentials. If the shared identity-provider Secret needs recovery, follow the backfill guidance.

After an approved recovery, repeat installation verification. For normal setup, return to Installing Policy.

6 - Uninstall Policy

Use this task as the platform operator to remove Policy. Choose Option A to keep data, or Option B to remove it. Helm removal does not withdraw policies from receiving products.

Before You Begin

Complete these prerequisites before uninstalling:

• Complete or resolve pending publication and withdrawal with the policy owner. Follow publication and withdrawal recovery.
• Verify a backup checkpoint when you need recovery. Preserve database credentials and required signing state separately.
• Confirm the release, namespace, and removal window with the platform owner. These examples use release policy in namespace pty-policy.
• Keep recoverable backups and credentials until you verify the chosen outcome.

Set the approved cluster context before running commands:

export CTX='your-approved-kubernetes-context'
kubectl --context "${CTX:?Set CTX to the approved context}" cluster-info
helm --kube-context "$CTX" --namespace pty-policy status policy

Confirm that the cluster and release match your removal request. Stop if either identity differs or remains uncertain. If Helm reports no release, confirm the prior uninstall in your change record. Then use Option B only after verifying ownership of the remaining resources.

Option A: Uninstall and Keep Data

To uninstall while retaining the data, follow these steps:

1. Record the release values and storage identities in your approved change record.

   helm --kube-context "${CTX:?Set CTX}" --namespace pty-policy get values policy
   kubectl --context "$CTX" --namespace pty-policy get pvc -o wide
   

   Record each claim, backing volume, chart version, and running image identity. Retain the three database usernames, their credential references, and the recovery plan. Do not copy secret values into the change record.

2. Confirm that no publication or withdrawal still requires the Policy workers. Archive acceptance alone does not prove completed removal. If protection must remain, obtain the receiving product owner’s approval.

3. Remove the release.

   helm --kube-context "${CTX:?Set CTX}" --namespace pty-policy uninstall policy --wait
   

   Helm removes chart-owned workloads and routes. The database claims and retained backup claim remain unless another controller removes them. The chart-owned shared identity provider (IdP) Secret does not remain.

4. Inspect the remaining workloads and storage.

   helm --kube-context "$CTX" --namespace pty-policy list --all
   kubectl --context "$CTX" --namespace pty-policy get \
     deployments,statefulsets,pods,services,jobs,cronjobs,pvc
   kubectl --context "$CTX" --namespace pty-policy get secrets
   

   Expect no Policy serving workloads and no installed policy release. Compare retained claim and Secret names with your recovery record. Investigate unexpected leftovers by ownership. Do not delete them automatically.

Verify Retained Data

Confirm that retained claims still reference the recorded volumes. Check that required credentials and external backup copies remain recoverable. If expected storage or credentials are missing, stop and involve the storage or identity owner.

To reinstall using retained data, follow retained-storage recovery. An ordinary fresh installation is not a recovery procedure.

Option B: Uninstall and Remove Data

Confirm Cleanup Inputs

Complete Option A first. Have the storage owner review volume reclaim policies, snapshots, and remote copies. Select the exact live database and backup claim names from the recorded inventory. The default backup claim is policy-db-backup-pvc. Verify actual names.

Warning: Deleting claims can irreversibly destroy database and backup data. Deleting a namespace removes every resource in it, including Secrets. Continue only with explicit data-loss approval and verified exclusive Policy ownership of pty-policy. Neither operation guarantees erasure of snapshots or remote copies.

Remove Approved Resources

To remove the approved resources, follow these steps:

1. Inspect the remaining claims before selecting deletion targets.

   kubectl --context "${CTX:?Set CTX}" --namespace pty-policy get pvc -o wide
   

   Confirm each selected claim’s exact name and backing volume with the storage owner.

2. Delete one explicitly approved claim at a time. Replace the example with the exact claim name before running:

   APPROVED_PVC='replace-with-one-approved-claim-name'
   kubectl --context "${CTX:?Set CTX}" --namespace pty-policy \
     get pvc "${APPROVED_PVC:?Set APPROVED_PVC}"
   read -r -p 'Type the claim name to approve its deletion: ' CONFIRMED_PVC
   if [ "$CONFIRMED_PVC" = "$APPROVED_PVC" ]; then
     kubectl --context "$CTX" --namespace pty-policy delete pvc "$APPROVED_PVC"
   else
     printf 'Claim confirmation did not match; nothing deleted.\n'
   fi
   

   Expect deletion only of the confirmed claim. Repeat for each approved live-data or backup claim. Do not use --all. If deletion stalls, ask the storage owner to investigate. Do not remove finalizers.

3. Complete external-resource cleanup. Revoke obsolete dedicated credentials through their owners. Do not revoke shared registry access or credentials needed for retained recovery.

4. Ask the platform owner to verify exclusive namespace ownership. Inspect all namespaced resource types, including custom resources:

   set -o pipefail
   kubectl --context "${CTX:?Set CTX}" api-resources \
     --verbs=list --namespaced -o name |
   while IFS= read -r RESOURCE_TYPE; do
     kubectl --context "$CTX" --namespace pty-policy \
       get "$RESOURCE_TYPE" --ignore-not-found || exit 1
   done
   

   Stop if any query fails or shows shared, unknown, or required recovery resources. Resolve external-secret or other controllers that could recreate resources. Resource labels alone do not prove exclusive ownership.

5. Remove the dedicated namespace only after the platform owner confirms that review. Otherwise, keep the namespace and delete only individually approved resources.

   read -r -p 'Type pty-policy after approval to delete the dedicated namespace: ' CONFIRMED_NAMESPACE
   if [ "$CONFIRMED_NAMESPACE" = 'pty-policy' ]; then
     kubectl --context "${CTX:?Set CTX}" delete namespace pty-policy
   else
     printf 'Namespace confirmation did not match; nothing deleted.\n'
   fi
   

   Expect namespace deletion after its resources finish terminating. A stuck namespace needs platform investigation, not forced finalizer removal.

Verify Cleanup

kubectl --context "${CTX:?Set CTX}" get namespace pty-policy --ignore-not-found

No output confirms namespace absence. If you deliberately retained the namespace, inspect it and confirm only approved resources remain. Ask the storage owner to confirm each volume’s intended deletion or retention. Verify external credential revocation and backup disposition through their owning systems.

For a clean reinstall, return to installation preparation. Proceed as fresh only after confirming that no old database will be reused.

7 - Policy Application Programming Interface

Use the Policy application programming interface (API) to author and govern policies. Track delivery separately from approval and target protection. Approval establishes a governed revision: the approved version of policy intent. A draft snapshot records saved proposal content, not another approved revision. Compilation produces target output. Publication and target activation happen separately. Begin with authentication and shared contracts.

Choose Your Path

Choose the API reference that matches your task:

• Complete an author-to-reviewer handoff with the worked lifecycle.
• Find an endpoint through the operation directory.
• Correct a failed request with error handling.
• Inspect retained failures through recovery and reconciliation.
• Understand background changes through automatic recompilation.

Operation Families

Choose the reference for the operation you need:

• Catalog, compilation, and preview
• Queries and drafts
• Submission, review, approval, and archive
• History and access
• Product retrieval and compatibility deployment
• Recovery and ownership reconciliation
• Authoring schemas
• Service operations and schema publication

The API base normally uses /pty/policy/v1.0, independently of the application version. Your deployed /swagger page and /doc document expose its schema. Use the endpoint-specific runtime rules here when conditional-header descriptions differ. An entity tag (ETag) is a server-issued resource validator. Draft commands use Draft-ETag. Archive uses the policy ETag. Copy the required token unchanged into If-Match to pin the command to inspected state. Do not substitute the governed policy validator for a current draft token.

7.1 - Authentication and Shared Request Contracts

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.

Examples assume Bash, curl, and a valid gateway-issued access token. Obtain your own token through your organization’s approved authentication flow. Use curl 7.76.0 or later for header-file support and --fail-with-body.

Prepare Credential-Safe Requests

Open a dedicated private Bash session for these requests. Do not reuse another participant’s shell or credential file. Set the endpoint without a trailing slash, then enter your token at the hidden prompt. Enter only the token value, without the Bearer prefix. The Bash built-ins keep that value out of external-process arguments and shell history.

set +x
set -euo pipefail
umask 077
POLICY_API="https://policy.example.com/pty/policy/v1.0"
unset PPC_ACCESS_TOKEN POLICY_TOKEN
POLICY_CREDENTIAL_DIR=$(mktemp -d "${TMPDIR:-/tmp}/policy-auth.XXXXXXXX")
POLICY_AUTH_HEADER="${POLICY_CREDENTIAL_DIR}/authorization.header"
trap 'rm -rf -- "$POLICY_CREDENTIAL_DIR"; unset PPC_ACCESS_TOKEN POLICY_AUTH_HEADER POLICY_CREDENTIAL_DIR' EXIT
trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM
IFS= read -r -s -p 'Your gateway access token: ' PPC_ACCESS_TOKEN
printf '\n'
if [[ ! "$PPC_ACCESS_TOKEN" =~ ^[A-Za-z0-9._~+/-]+=*$ ]]; then
  unset PPC_ACCESS_TOKEN
  printf 'Invalid bearer token format; obtain a token through the approved flow.\n' >&2
  exit 1
fi
builtin printf 'Authorization: Bearer %s\n' "$PPC_ACCESS_TOKEN" > "$POLICY_AUTH_HEADER"
unset PPC_ACCESS_TOKEN

The private directory permits only its owner to access it. The header file permits only its owner to read or write it. Do not export token variables or copy this file into shared storage. The examples pass only its path to curl, leaving standard input available for payloads. Keep this shell open while running the requests.

Send the token through the protected header file:

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

Keep tokens out of unprotected or retained files, shared transcripts, source control, and screenshots. Do not enable shell tracing or curl verbose output around credentials. Do not print the header file or log authorization headers. Use normal certificate verification. Do not copy examples with -k. Obtain each user’s credentials separately through your approved login flow.

Clean up Credentials

Exit the dedicated shell when you finish or hand off to another participant:

exit

The exit trap deletes the header file and its private directory. It also clears the credential-path variables. Forced termination or a host crash can prevent trap execution. Remove that session’s private directory through approved local cleanup if this happens. Do not retain credential files with response evidence.

Policy Panel Cookie Fallback

Request-driven deployment accepts the gateway’s accessToken cookie when the request omits the authorization header. An explicit blank, malformed, or non-bearer header prevents fallback. Use the gateway’s normal browser protections. Do not spoof forwarded identity. Policy does not require a separate cross-site request forgery token for these lifecycle commands.

Capabilities and Policy Access

A capability authorizes a command, such as approval. A policy grant provides owner/editor access to one policy. Operations that require both reject callers who hold only one.

Responsibilities do not create product roles. In particular, Policy does not define a separate policy_reviewer role. Different authenticated users can author, review, and approve. These command contracts do not themselves enforce two different people. Follow any additional separation-of-duties rules that your organization requires.

The following table maps each responsibility to its required capability or policy grant:

Creation requires policy:edit and grants the creator policy ownership. An owner/editor grant never creates review, approval, or audit capability. Grant management requires an active policy owner or an authorized recovery override. The recovery override remains attributable and auditable. Do not request broad administrative access merely to complete a review example.

Trusted Authority Mappings

The following table lists trusted authorities and the capabilities each one grants:

Policy combines mapped authorities. Unmapped authorities grant no capabilities. Ask your access administrator for the approved deployment mapping. An operations read does not authorize a retry mutation. Gateway access rules also apply to backend reads that preserve optional-identity compatibility.

Conditional Requests

An entity tag (ETag) is a server-issued validator for a resource’s inspected state. The If-Match request header carries that validator as a command precondition. Use the validator for the resource that the command actually changes.

Use this table to choose the required validator for each command:

Treat every validator as opaque. Copy it exactly, including quotes and any weak-token prefix. Policy reads return both policy and draft validators where applicable. Saved-validation responses also identify the exact head through Draft-ETag and draftEtag. Draft summaries expose the token as etag. Snapshot identifiers identify saved content. Validators protect conditional requests. Do not use draftVersionId, currentVersionId, or a numeric policy version as a validator.

Submission advances the draft head. The reviewer must read the submitted head before approving it. Do not reuse the author’s pre-submit token. After a conflict, review intervening changes before issuing another command.

Missing required validators return 428. Draft save, submit, and approval reject a non-draft token with 400. A changed draft head normally returns 409 with current draft context. Request-changes also returns 409 for token mismatch or a non-review head. Policy and registry version conflicts can return 412. Refer to error reference for response shapes.

Deployment Authentication

Background publication and withdrawal use configured integration credentials. Request-driven compatibility deployment forwards the authenticated user’s token to Policy Integration Manager (PIM). That user also needs PIM permission for the requested native changes. Do not use compatibility deployment for normal governed publication. Approval queues that publication asynchronously.

Guardrails product-policy reads can record delivery evidence. GUARDRAILS_CONSUMER_USERNAME selects the eligible consumer identity. It does not authenticate callers. The empty-string default permits receipts only for requests with absent or empty identity. It does not permit named requests. A nonempty setting requires an exact gateway-verified username match. Qualifying 200 and 304 retrievals can both record receipts. Anonymous reads do not qualify with a nonempty setting. Diagnostics under another identity do not qualify. Keep the consumer’s credentials separate from human and other service credentials. Neither receipt nor publication proves downstream activation.

The chart maps apiService.environment.GUARDRAILS_CONSUMER_USERNAME through the API ConfigMap into the environment. This setting does not change gateway access rules. Refer to Guardrails consumer evidence for the supported default and completion boundaries.

7.2 - Policy API Operation Directory

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:

• Catalog and authoring covers input discovery, compilation, and preview.
• Queries and drafts covers policy reads and draft changes.
• Governance covers submission, review, approval, and archive.
• History and access covers lineage, audit export, and grants.
• Delivery covers consumer retrieval and compatibility deployment.
• Recovery and reconciliation covers diagnostics, retry, and ownership decisions.
• Authoring schemas covers Cedar, actions, and attribute vocabulary.
• Service operations covers health, logs, metrics, and published schemas.

Follow the worked lifecycle for save, submission, separate-user review, approval, and delivery inspection. The entries below retain earlier endpoint anchors.

GET /version

Refer to canonical operation reference.

GET /doc

Refer to canonical operation reference.

GET /log

Refer to canonical operation reference.

POST /log

Refer to canonical operation reference.

GET /health

Refer to canonical operation reference.

GET /ready

Refer to canonical operation reference.

GET /live

Refer to canonical operation reference.

GET /catalog

Refer to canonical operation reference.

POST /catalog/recommend

Refer to canonical operation reference.

GET /catalog/principals

Refer to canonical operation reference.

GET /catalog/resources

Refer to canonical operation reference.

GET /catalog/actions

Refer to canonical operation reference.

POST /policies/compile

Refer to canonical operation reference.

GET /policies

Refer to canonical operation reference.

GET /policies/{policy_id}

Refer to canonical operation reference.

GET /policies/{policy_id}/access-grants

Refer to canonical operation reference.

POST /policies/{policy_id}/access-grants

Refer to canonical operation reference.

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

Refer to canonical operation reference.

POST /policies

Refer to canonical operation reference.

PUT /policies/{policy_id}

Refer to canonical operation reference.

GET /policies/{policy_id}/validation

Refer to canonical operation reference.

GET /validation-diagnostics/{support_reference}

Refer to canonical operation reference.

DELETE /policies/{policy_id}

Refer to canonical operation reference.

POST /policies/{policy_id}/submit

Refer to canonical operation reference.

POST /policies/{policy_id}/request-changes

Refer to canonical operation reference.

POST /policies/{policy_id}/approve

Refer to canonical operation reference.

POST /policies/{policy_id}/archive

Refer to canonical operation reference.

GET /policies/{policy_id}/versions

Refer to canonical operation reference.

GET /policies/{policy_id}/history

Refer to canonical operation reference.

GET /policies/{policy_id}/audit-export

Refer to canonical operation reference.

GET /policies/{policy_id}/operations

Refer to canonical operation reference.

GET /policies/{policy_id}/pim-reconciliations

Refer to canonical operation reference.

POST /policies/{policy_id}/pim-reconciliations

Refer to canonical operation reference.

GET /pim-reconciliations/bindings

Refer to canonical operation reference.

GET /pim-reconciliations

Refer to canonical operation reference.

POST /pim-reconciliations

Refer to canonical operation reference.

POST /policies/{policy_id}/deployments/{deployment_id}/retry

Refer to canonical operation reference.

POST /policies/{policy_id}/archive-evidence

Refer to canonical operation reference.

GET /product-policies/{product_type}

Refer to canonical operation reference.

POST /product-policies/{product_type}/acknowledgements

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

POST /policies/preview

Refer to canonical operation reference.

POST /policies/{policy_id}/deploy

Refer to canonical operation reference.

POST /policies/{policy_id}/deploy/securequery

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

GET /securequery-profiles

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

POST /securequery-profiles

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

GET /securequery-profiles/{profile_uuid}

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

PUT /securequery-profiles/{profile_uuid}

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

POST /securequery-profiles/{profile_uuid}/status

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

POST /securequery-profiles/{profile_uuid}/validate

This release does not register this route. Do not call it. Refer to product delivery for current consumer contracts.

GET /schema/cedar

Refer to canonical operation reference.

GET /schema/actions

Refer to canonical operation reference.

GET /schema/authoring-actions

Refer to canonical operation reference.

GET /schema/attributes

Refer to canonical operation reference.

7.3 - Save, Review, Approve, and Inspect Delivery

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.

Prepare Safe Variables

Each participant supplies only their own token in their own session. Complete the credential-safe request setup in each participant’s dedicated Bash session. Each participant creates their own protected header file through the hidden prompt. Use the same POLICY_API and policy identifier across the handoff. Do not enable shell tracing, print the token, or log authorization headers. Follow credential cleanup when each participant finishes.

set -euo pipefail
: "${POLICY_API:?Set the deployment endpoint during authentication setup}"
: "${POLICY_AUTH_HEADER:?Complete authentication setup with your own author token}"

Retain only safe response bodies and headers, never the temporary credential file. The helper preserves the exact draft token:

draft_etag() {
  awk '
    tolower($1) == "draft-etag:" {
      sub(/\r$/, "")
      sub(/^[^:]*:[[:space:]]*/, "")
      value = $0
    }
    END {
      if (value == "") exit 1
      print value
    }
  ' "$1"
}

Save as the Author

As the author, complete these steps to prepare and save the draft:

1. Retrieve the current selection catalogs.

   curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/catalog" -o catalog.json
   curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/catalog/principals" -o principals.json
   curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/catalog/resources" -o resources.json
   

   The responses identify available classifications, principals, and discovered resources. Choose a PIM-supported principal and matching resource classification. Stop if integration evidence or supported selections are missing.

2. Set the selected catalog identifiers in your session.

   : "${CLASSIFICATION:?Set an exact classification identifier from the catalog}"
   : "${PRINCIPAL_ID:?Set the selected supported principal identifier}"
   : "${RESOURCE_ID:?Set the selected matching discovered resource identifier}"
   

3. Generate the complete create payload.

   jq -n \
     --arg classification "$CLASSIFICATION" \
     --arg principal "$PRINCIPAL_ID" \
     --arg resource "$RESOURCE_ID" \
     '{
       readableName: "Reviewed customer record protection",
       source: "data",
       compileRequest: {
         classificationsInScope: [$classification],
         enforcement: [{
           enforcementPoint: "data-protection",
           effect: "permit",
           anyPrincipal: false,
           principalIds: [$principal],
           actions: ["viewNull"],
           resourceIds: [$resource]
         }],
         protectionIntents: [{classification: $classification}]
       }
     }' > create-policy.json
   

   The server derives protection methods from the selected inputs. An empty actions list does not mean null-read permission. Optional trusted applications belong in compileRequest.trustedApplications, separately from permission principals.

4. Save the draft.

   curl --fail-with-body -X POST \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -H "Content-Type: application/json" \
     --data-binary @create-policy.json \
     -D create.headers -o create-response.json \
     "${POLICY_API}/policies"
   POLICY_ID=$(jq -er '.policy.id' create-response.json)
   DRAFT_ETAG=$(draft_etag create.headers)
   jq '.policy | {id, policyState, draftState, outstandingExceptions}' \
     create-response.json
   

   Expect 201, a policy identifier, and a Draft-ETag header. Save creates a draft. It does not approve or publish it. Save can retain validation findings that prevent later submission. Keep POLICY_ID for policy paths. Do not replace it with draftPolicyId or a snapshot identifier. The draftPolicyId identifies the stable Draft Policy. The draft summary’s cycleNumber identifies its cycle.

Submit and Hand Off

As the author, complete these steps to submit the current draft and hand it off:

1. Submit the exact saved head as the author.

   curl --fail-with-body -X POST \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -H "If-Match: ${DRAFT_ETAG}" \
     -D submit.headers -o submit-response.json \
     "${POLICY_API}/policies/${POLICY_ID}/submit"
   jq '.policy | {id, policyState, draftState, enforcementState}' \
     submit-response.json
   

   Expect 200 with the draft entering in_review. Submission advances its token and queues no publication. If validation blocks submission, stop and inspect the returned safe findings. Correct hard conflicts. Do not manufacture acknowledgements. For reviewable findings, follow the notes and conflict-identifier requirements in the submission contract.

2. Give the reviewer the policy identifier and review context.

   Do not give them your token or pre-submit validator. They authenticate separately and retrieve the current submitted content.

Review as Another User

As the reviewer, complete these steps to review the submitted draft:

1. Authenticate in the reviewer’s session.

   Complete the credential-safe request setup with the reviewer’s own token in a separate dedicated Bash session. Do not copy the author’s credential file or token.

   set -euo pipefail
   : "${POLICY_API:?Set the same deployment endpoint during authentication setup}"
   : "${POLICY_ID:?Use the policy identifier supplied for review}"
   : "${POLICY_AUTH_HEADER:?Complete authentication setup with your own reviewer token}"
   

2. Read the current policy.

   curl --fail-with-body \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -D review.headers -o review-policy.json \
     "${POLICY_API}/policies/${POLICY_ID}"
   jq '.policy' review-policy.json
   

   Review the scope, principal permission, method, and current draft state. Stop if the draft no longer represents the submitted proposal.

3. Refresh saved validation with review authority.

   curl --fail-with-body \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -D validation.headers -o validation.json \
     "${POLICY_API}/policies/${POLICY_ID}/validation"
   jq -e '.draftStatus == "in_review" and .cedarValid == true
     and (.conflicts | length == 0)' validation.json
   REVIEWED_DRAFT_ETAG=$(jq -er '.draftEtag' validation.json)
   

   Expect 200, current draft identifiers, findings, and the same token in Draft-ETag. This clean-path example stops when conflicts exist. An author without review capability cannot use this endpoint. The approver must reconsider any changed findings before acknowledgement. Compare the validated head with the content just reviewed. If it changed during the handoff, reread the content before approving. Do not parse the token to infer that content stayed unchanged.

4. Approve the submitted draft using the validator returned by validation.

   curl --fail-with-body -X POST \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -H "Content-Type: application/json" \
     -H "If-Match: ${REVIEWED_DRAFT_ETAG}" \
     --data '{"reviewNotes":"Reviewed selected scope and null-read permission.","acknowledgedConflictIds":[]}' \
     -o approve-response.json \
     "${POLICY_API}/policies/${POLICY_ID}/approve"
   jq '.policy | {id, policyState, governedRevision, draftState, enforcementState}' \
     approve-response.json
   

   Expect 200, a governed revision, and asynchronous publication work. Policy revalidates current dependencies before accepting approval. A stale token or changed validation requires another review, not blind retry. Never send approvedBy. Policy records the authenticated approver.

Request Changes Instead

The reviewer can return the submitted head without changing its authored content:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${REVIEWED_DRAFT_ETAG}" \
  --data '{"reason":"Narrow the selected resource scope before approval."}' \
  "${POLICY_API}/policies/${POLICY_ID}/request-changes"

Expect 200 with draft.draftStatus: "changes_requested" and a new draft.etag. The author reloads the returned draft, corrects the complete compileRequest, saves through PUT /policies/{policy_id}, and submits again. Use the new current draft token for each command. This alternative replaces approval. Do not execute it after approving.

Inspect Delivery as an Auditor

As an auditor, complete these steps to inspect delivery evidence:

1. Authenticate as an authorized auditor and inspect operations.

   Complete the credential-safe request setup with the auditor’s own token in a separate dedicated Bash session. Do not copy the author’s or reviewer’s credential file or token. Set POLICY_API and POLICY_ID to the same endpoint and policy used in the handoff.

   : "${POLICY_AUTH_HEADER:?Complete authentication setup with your own auditor token}"
   curl --fail-with-body \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/policies/${POLICY_ID}/operations" \
     -o operations.json
   jq '.[] | {deploymentId, generation, operation, enforcementState,
     retryable, attemptCount, diagnostics}' operations.json
   

   Expect 200 with a top-level operation array. Retain the deployment identifier and generation for any authorized recovery.

2. Read current protection evidence separately.

   curl --fail-with-body \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/policies/${POLICY_ID}?view=governed&includeProtection=true" \
     -o delivery-policy.json
   jq '.policy | {policyState, governedRevision, enforcementState, protectionConfirmation}' \
     delivery-policy.json
   

   The governed view selects approved inputs, not an open replacement draft’s scope. The default view=latest selects that draft’s content instead. Compare the current governed revision, deployment, and expected locations with current observations. Approval, successful publication, and consumer receipt do not independently prove protection. Verify target-specific behavior through your approved protection checks.

Verification and Failure Boundaries

Keep the saved policy identifier, reviewed draft version, governed revision, deployment generation, and safe validation evidence. History attributes the submitter and approver to their actual identities. Review or audit capability controls restricted decision-note visibility.

For 409 or 412, reread and reassess intervening changes. For missing authority, stop and request the appropriate approved access. For publication failures, follow the recovery playbook. Do not call compatibility deployment to force governed publication. Retained retry does not compile corrected drafts.

7.4 - Application Programming Interface Errors and Safe Recovery

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:

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.

An operations 404 can mean no recorded deployments. A diagnostics 404 can mean expired evidence. A saved-validation 404 can mean no draft. Read the status-code description for the endpoint you called before deciding what to retry.

Error Response Shapes

Common service errors use message and optional causedBy fields. Workflow errors use detail, which can contain a string, object, or validation list. Do not assume every error contains detail.code.

Compile, submission, and approval can return structured validation failures. The following example illustrates an approval failure. Do not expect its code from every operation:

{
  "detail": {
    "code": "approval_validation_failed",
    "message": "Approval cannot continue until the validation findings are resolved.",
    "conflicts": [],
    "issues": [
      {
        "path": "$.user_attribute",
        "constraint": "required",
        "message": "Set the identity source user attribute."
      }
    ],
    "supportReference": "VAL-example"
  }
}

An authorized auditor can retrieve retained evidence through validation diagnostics. Records expire after seven days. The support reference itself does not authorize access. If you lack policy:audit, retain the safe failure response and reference for an authorized auditor. Compare each issues[].path with the request schema for the endpoint. If the message describes an identity-source setting, as in the example, send it and the support reference to the identity integration administrator. Do not add an unfamiliar configuration field to your policy request merely because the error names it.

Draft conflicts can include detail.currentDraft, with the current etag, currentVersionId, and draft identity. Reload policy detail and compare the saved draft with your intended changes before retrying. Archive-evidence location conflicts can include detail.unexpectedLocationIds. Ownership conflicts can include the changed affected-policy set or revision map. Ordinary schema failures can contain a validation-error list instead. For a changed draft, read current content and validation with the required authority. Correct the selected input or review the new findings before resubmitting. After retrying, reload the policy to check the saved content and status. For publication failures, follow the delivery verification guides.

Retry and Idempotency Guidance

No general idempotency key makes every lifecycle command replay-safe. After a timeout, first read current policy, history, and permitted operation evidence. The server might have accepted a command before the connection failed.

Reconciliation decisions require an Idempotency-Key. An identical accepted decision can replay without another ownership transition. Keep the original actor, body, registry token, and key for that exact replay. Changed evidence requires inspection and a new decision.

Retained deployment retry requires no general idempotency key. It restarts eligible work that stopped after failure. A repeated request can return 409 while that work is already running again. Archive-evidence submission can append another immutable event when repeated. Check history before repeating it after an uncertain result.

Endpoint Groups and Expected Error Patterns

Use this table to identify the correction boundary for each operation family:

Only acknowledge conflicts that explicitly permit acknowledgement. Never acknowledge a hard validation failure or shared-protector permission widening. An author without review capability cannot use saved validation as an unrestricted diagnostic shortcut. An operator may need to repair integrations before the author can continue.

For ownership mismatches, use explicit reconciliation inspection and allowed decisions. Do not assume waiting for a background refresh authorizes adoption or replacement. Retrying delivery reuses retained artifacts. It does not compile corrected drafts. There is no public run-now endpoint for automatic recompilation.

7.5 - Service and Schema Publication Operations

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.

GET /version

Retrieve runtime API version.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Version object.

Sample response:

{
  "version": "1.1",
  "buildVersion": "1.1.0"
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /doc

Retrieve OpenAPI specification as YAML. OpenAPI describes request and response schemas. YAML is the document format returned by this route.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

OpenAPI YAML document.

Sample response:

openapi: 3.1.0
info:
  title: Policy Compiler API

Error codes:

Possible error codes are 401, 403, and 500.

GET /log

Retrieve current runtime log level. This operation returns the configured level, not log entries or diagnostic records.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Current log level.

Sample response:

{
  "level": "info"
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /log

Update runtime log level. Require policy:system-configure. This change applies to the serving process, not persistent cluster configuration.

Path parameters

None.

Request body

JSON with desired log level.

Request parameters

None.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -d '{"level":"debug"}' \
  "${POLICY_API}/log"

Response

Updated log level.

Sample response:

{
  "level": "debug"
}

Error codes:

Possible error codes are 400, 401, 403, and 500.

PUT /log

Use the compatibility method for the same process-local log update. Require policy:system-configure. Accept no path or query parameters. Send an application/json object with the required string level. Supported values include debug, info, warn, and error. The server also accepts legacy uppercase forms.

curl --fail-with-body -X PUT \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data '{"level":"info"}' \
  "${POLICY_API}/log"

Return 200 with {"level":"info"}. Return 400 for invalid levels, 401 or 403 for identity or capability failures, or 500 for server failures. Neither log-update method requires If-Match or an idempotency key.

GET /health

Retrieve service health status.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Health status object with component checks.

Sample response:

{
  "isHealthy": true,
  "checks": [
    {
      "passed": true,
      "output": "Catalog loaded successfully",
      "componentType": "catalog",
      "componentName": "catalog"
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 503.

GET /ready

Readiness probe endpoint.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Empty body with readiness status code.

Sample response:

HTTP/1.1 204 No Content

Error codes:

Possible error codes are 401, 403, and 503.

GET /live

Liveness probe endpoint.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Empty body with liveness status code.

Sample response:

HTTP/1.1 204 No Content

Error codes:

Gateway authentication or authorization failures return 401 or 403. Liveness failures return 503.

GET /openapi.json

Retrieve the generated OpenAPI schema as JavaScript Object Notation (JSON). Accept no body, path parameters, or query parameters. Apply gateway authentication as your deployment requires. Return 200 with the schema document. Gateway failures can return 401 or 403. Server failures can return 500. This automatic schema route does not appear as an operation inside its own document.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/openapi.json"

GET /swagger

Open the browser reference for the deployed schema. Accept no body or parameters. Return 200 with Hypertext Markup Language (HTML). The page loads its schema and initializer from the same API root. Gateway failures can return 401 or 403. Rendering failures can return 500.

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

GET /swagger/init.js

Serve the Swagger browser initializer. Accept no body or parameters. Return 200 with JavaScript. This auxiliary route supports the browser reference, not policy mutation. Gateway failures can return 401 or 403. Server failures can return 500.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/swagger/init.js"

GET /favicon.ico

Serve the browser reference’s empty icon response. Accept no body or parameters. Return 200 with the image/x-icon media type. This auxiliary route carries no policy or health evidence. Gateway failures can return 401 or 403.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/favicon.ico"

GET /metrics

Read service metrics in Prometheus exposition format. Require policy:observability. Accept no body or parameters. Return 200 with metric text, not a JSON response. Return 401 or 403 for identity or observability failures. Metrics collection can also encounter server failures. This route does not appear in the generated operation schema.

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

Use metrics with operation history and automatic recompilation observations. Check authenticated catalog access separately. A successful health probe does not test every integration operation. For a failed probe, retain the status, timestamp, and safe health-check output when available. Ask the platform operator to investigate readiness or dependency failures. Wait for the operator to restore service before repeating an authoring request.

7.6 - Catalog, Compilation, and Preview Operations

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) 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.

Build each compile request from current catalog selections. Use classification identifiers from /catalog, principal id values from /catalog/principals, and resource id values from /catalog/resources. Place principal and resource identifiers in the corresponding enforcement row’s principalIds and resourceIds arrays. Use the exact ID returned by the appropriate current catalog. Do not substitute a display label or an identifier from a different API. Catalog retrieval does not populate a server-side authoring session. Send the complete accumulated input with each compile or preview request.

GET /catalog

Retrieve Policy catalog vocabulary bundle.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Catalog bundle.

Sample response:

{
  "classifications": ["EMAIL_ADDRESS"],
  "classificationDetails": {
    "EMAIL_ADDRESS": {"label": "Email address"}
  },
  "protectionMethods": ["FPE"]
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /catalog/recommend

Recommend protection methods for supplied items.

Path parameters

None.

Request body

Items with classification and profile toggles.

The table lists item fields, their data types, and requirements or defaults:

Place items in the top-level items array. Omission defaults to an empty array. The response omits items whose classification yields no modeled method. Recommendation does not establish that every method supports your selected target.

Request parameters

None.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"customer_email","classification":"EMAIL_ADDRESS"}]}' \
  "${POLICY_API}/catalog/recommend"

Response

Recommended methods per item.

Sample response:

{
  "methods": {
    "customer_email": "FPE"
  }
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

GET /catalog/principals

Retrieve principal catalog for the Who step.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Principal entries and total count. When identity-source provenance is available, entries include normalized provider values, the source-supplied discovery.principalUuid, and pimSupported. Unsupported Data Protection principals include a pimUnsupportedReason. Unknown source compatibility is left unset rather than inferred.

Use each entry’s exact id for policy selection. name is a display label. Do not infer an ID format or reject a UUID that the catalog returns. Select a PIM-supported principal for Data authoring. An unset pimSupported value does not establish support. Directory membership does not grant Policy command authority.

Sample response:

{
  "total": 1,
  "principals": [
    {
      "id": "user-123",
      "name": "Example reader",
      "type": "User",
      "provider": "IDP",
      "discovery": {
        "principalUuid": "{{PRINCIPAL_UUID}}",
        "sourceId": "{{IDENTITY_SOURCE_ID}}",
        "sourceSystem": "idp_ldap"
      },
      "pimSupported": true,
      "pimUnsupportedReason": null
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /catalog/resources

Retrieve resource catalog for the Protection step.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Resource entries and total count.

Use the returned resource id in the compile request. Catalog protection labels describe discovered or derived information, not confirmed target activation. If a required resource is missing, ask the discovery integration owner to check its source. Do not fabricate an identifier to bypass missing discovery evidence.

Sample response:

{
  "total": 1,
  "resources": [
    {"id":"schema.table.column","name":"Example column","type":"Column"}
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /catalog/actions

Retrieve action catalog for permissions matrix. This catalog differs from the native and abstract authoring action vocabularies. Use /schema/authoring-actions for abstract compile actions and /schema/actions for native schema actions.

Path parameters

None.

Request body

None.

Request parameters

None.

Sample request:

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

Response

Action vocabulary.

Sample response:

{
  "actions": [
    {
      "id": "ca-1",
      "name": "read",
      "category": "data-access",
      "applicableLayers": [1, 2, 3, 4, 5],
      "description": "Read/select rows from a table or column"
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /policies/compile

Compile a policy and return its validation report and emitted entities.

Path parameters

None.

Request body

Compile request payload. The optional trustedApplications array contains application gates for PIM datastores, separate from user and group permission principals. Each entry has an applicationName and one or more applicationUsers. Refer to deployed OpenAPI document for field constraints.

Request parameters

None.

The public compile body accepts these top-level fields:

Use the deployed schema for typed configOverrides and native rule definitions. An empty request can span broad discovery inputs. Prefer explicit bounded scope. Compilation returns findings without creating a draft or changing protection. Inspect the returned report, not only the 200 status. Neither compiled entities nor a successful preview establish submission eligibility or target protection.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  "${POLICY_API}/policies/compile"

Response

Final compile report plus Cedar and PIM entities.

Sample response:

{
  "report": {},
  "cedarEntities": [],
  "pimEntities": []
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

POST /policies/preview

Preview a policy’s native lowering without applying changes.

Path parameters

None.

Request body

Product-specific preview payload. Use product=PIM for a bare compile request. Use product=FEDX for a Federated Guardrails object with required compile and optional guardrail_rules, dataprotection_rules, content_action_rules, or federated_matrix.

Request parameters

product is required and accepts PIM or FEDX. The optional boolean reuse_existing defaults to true for PIM inventory reuse. Inventory reuse concerns native resource planning. It is not a replay or idempotency guarantee.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  "${POLICY_API}/policies/preview?product=PIM&reuse_existing=true"

Response

Product-specific native plan object. For product=PIM, datastore_scopes can contain an individual registration scope or a shared protector-group scope. Group scopes retain each source registration, its approved IPv4 ranges, and source columns, alongside the group’s canonical range union. The plan can also include source-sensitive authorization evidence used to check that sharing a native datastore does not widen permissions.

Sample response:

{
  "plan": {
    "operations": [],
    "datastore_scopes": {
      "{{DATASTORE_GROUP_REF}}": {
        "schema_version": 2,
        "group_id": "{{PROTECTOR_GROUP_ID}}",
        "ranges": [["192.0.2.10", "192.0.2.10"]],
        "sources": [{
          "registration_id": "{{SOURCE_REGISTRATION_ID}}",
          "ranges": [["192.0.2.10", "192.0.2.10"]],
          "source_columns": ["{{SOURCE_COLUMN_ID}}"]
        }]
      }
    },
    "authorization": {
      "schema_version": 1,
      "policy_id": "${POLICY_ID}",
      "resources": [],
      "native_grants": []
    }
  }
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

7.7 - Policy Queries and Draft Operations

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.

GET /policies

List visible policy summaries and aggregate counters. The backend permits optional identity for this compatibility read. Gateway access rules still apply. Accept no body or path parameters.

The following table lists supported query parameters and their types and behavior:

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

Return 200 with total, dataCount, aiCount, approvedCount, draftCount, and a policies array. Each summary identifies id, compatibility status, source, and independent policyState, draftState, and enforcementState values. Additional fields describe names, scope, method, validation, and available actions.

governedRevision identifies the approved major revision. governedMinorVersion identifies compilation output within that revision. draftPolicyId, draftCycleNumber, and proposedRevisionNumber identify open draft work. hasOpenDraft distinguishes an approved policy with a replacement proposal. validationStatus describes authoritative, unavailable, or stale saved validation. operationIssue summarizes delayed or failed delivery. availableActions lists actions offered to the caller. A command can still fail if permissions or policy content change after the read.

Counters use the search-filtered set before the status filter. For bounded reads, send limit and offset explicitly and retain the same filters and view on later pages. Do not use aggregate counters as page lengths. includeProtection=true queries the integrations for current protection observations and can take longer than a stored-state read. Gateway failures can return 401 or 403. Malformed query values return 422. Dependency failures can return 503. Server failures can return 500.

GET /policies/{policy_id}

Inspect one policy’s full content and independent state projections. Require the policy_id path string. Accept no body. Support the same includeProtection and view query options as listing. The backend permits optional identity. Gateway access rules still apply.

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

Return 200 with a policy object. The object includes id, readableName, version, status, authored fields, trusted actor attribution, validation findings, and independent state projections. Imported external records can expose origin, displayOnly, and editable. includeProtection=true can populate protectionConfirmation. The response supplies the policy ETag and, when available, Draft-ETag. Draft commands require the latter. Use view=latest to inspect current proposal content before a draft command. Use view=governed to inspect approved content while a replacement draft remains open. A policy’s approved governance state does not make its open draft approved.

{
  "policy": {
    "id": "policy-1",
    "status": "approved",
    "policyState": "approved",
    "governedRevision": 3,
    "governedMinorVersion": 1,
    "hasOpenDraft": true,
    "draftState": "in_review",
    "enforcementState": "enforced"
  }
}

Return 404 for an unknown policy. Gateway failures can return 401 or 403. Invalid query values return 422. Live integration failures can return 503. Server failures can return 500.

POST /policies

Create a new policy identity and its first saved draft. Require policy:edit. Accept no path or query parameters. Creation grants policy ownership to the authenticated creator. No prior validator or idempotency key applies.

The application/json body rejects extra fields:

Policy recomputes validation from compileRequest. Client conflict lists and client lifecycle states cannot bypass those checks. Do not send status, createdBy, or another actor. Refer to worked example for a complete create payload.

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @create-policy.json \
  "${POLICY_API}/policies"

Return 201 with the full policy object and policy/draft validator headers. Save can retain incomplete work and findings. It does not guarantee submission eligibility. Return 401 or 403 for identity or edit failures, 422 for invalid input, or 500 for server failures. After a timeout, list policies and check the matching policy’s detail and history before creating another policy.

PUT /policies/{policy_id}

Save, open, or restore draft work. Require the policy_id path string and current Draft-ETag through If-Match. Accept no query parameters. Normal editing requires policy:edit plus an active owner/editor grant. Rollback requires policy:rollback plus that grant. Authorized recovery overrides remain audited.

The application/json body supports three forms:

sourceVersion is an integer governed revision number, at least one. reason accepts 1–512 characters. confirmDraftVersionId identifies the exact current snapshot that rollback replaces. Obtain that identifier from the current draft summary’s currentVersionId or saved validation’s draftVersionId. It differs from sourceVersion, which selects the governed revision to restore. Never send compileRequest alongside sourceVersion. Rollback restores server-held governed content into a new in-review draft. It does not immediately replace the currently governed revision. The body rejects unknown fields, including direct lifecycle-state changes.

Before running this normal-save example, prepare update-policy.json with the complete current compileRequest. Use the worked payload construction for its shape, and retain the authored fields you intend to save. Obtain DRAFT_ETAG from a current policy read before sending the request.

curl --fail-with-body -X PUT \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${DRAFT_ETAG}" \
  --data-binary @update-policy.json \
  "${POLICY_API}/policies/${POLICY_ID}"

Return 200 with the full policy and latest policy/draft validators. Saving replacement work preserves the existing governed revision and delivery. Return the following error codes:

• 400 for the wrong token type.
• 401 or 403 for authority failures.
• 404 for missing context.
• 409 for a changed head or illegal state.
• 412 for persistence races.
• 422 for invalid input.
• 428 for a missing token.

GET /policies/{policy_id}/validation

Revalidate the exact saved draft snapshot. Require policy:review, not merely authorship or an owner/editor grant. Require the policy_id path string. Accept no body or query parameters. This read requires no If-Match.

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

Return 200 with:

The Draft-ETag header identifies the same saved head. Policy excludes archived policies from cross-policy conflict snapshots. Return the following error codes:

• 401 or 403 for identity or review failures.
• 404 without a draft.
• 409 without a current saved snapshot or after a concurrent head change.
• 422 for invalid saved compile input.

Server failures can return 500. After a changed-head response, reread and review before deciding.

DELETE /policies/{policy_id}

Cancel the open draft cycle without deleting retained history. Require policy:edit and an active owner/editor grant, or an audited recovery override. Require the policy_id path string and current draft token through If-Match. Accept no body or query parameters.

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

Return 200 with the restored full policy. An existing governed revision remains current. Previous draft snapshots remain in history. This operation does not archive governed protection or erase audit evidence. Return 400, 401, 403, 404, 409, 412, or 428 for token, authority, missing-context, state, or concurrency failures.

7.8 - Submission, Review, Approval, and Archive Operations

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.

POST /policies/{policy_id}/submit

Submit the exact saved draft for review. Require policy:edit and an active owner/editor policy grant. An audited recovery authority can override the grant requirement. Send the current Draft-ETag through If-Match.

The body is optional for clean work. When acknowledging permitted reviewable conflicts, supply:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "If-Match: ${DRAFT_ETAG}" \
  "${POLICY_API}/policies/${POLICY_ID}/submit"

Optional acknowledgement body:

{
  "reviewNotes": "Reviewed the permitted findings and accepted their documented impact.",
  "acknowledgedConflictIds": ["current-reviewable-conflict-id"]
}

Return 200 with a policy summary and updated ETag and Draft-ETag headers. The compatibility status becomes submitted. draftState becomes in_review. Policy checks the saved validation binding and recompiles against current catalogs. Hard conflicts cannot receive acknowledgement. An eligible returned draft can enter review again without an intermediate save. Submission does not approve or publish. Reload the submitted draft and use its new Draft-ETag for the review decision. The token from before submission no longer identifies the current draft.

POST /policies/{policy_id}/request-changes

Return the current in-review draft to its author. Require policy:review, not an owner/editor grant. Send the reviewed current draft token through If-Match.

The request body contains this required reason field:

The current request schema enforces this reason length.

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${DRAFT_ETAG}" \
  --data '{"reason":"Narrow the resource scope before approval."}' \
  "${POLICY_API}/policies/${POLICY_ID}/request-changes"

Return 200 with the new draft summary:

{
  "draft": {
    "policyId": "policy-1",
    "draftPolicyId": "draft-1",
    "cycleNumber": 1,
    "proposedRevisionNumber": 1,
    "currentVersionId": 43,
    "draftStatus": "changes_requested",
    "etag": "W/\"draft-1.1.43\""
  }
}

Use the returned draft.etag for subsequent draft work. Policy preserves authored content and records the reviewer’s decision. An existing governed revision remains current.

POST /policies/{policy_id}/approve

Approve the exact reviewed in-review draft. Require policy:approve. Policy ownership alone does not grant approval. Send its current Draft-ETag through If-Match. Do not reuse the author’s token from before submission.

The required approval body accepts these review notes and conflict identifiers:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${DRAFT_ETAG}" \
  --data '{"reviewNotes":"Reviewed current intent and validation.","acknowledgedConflictIds":[]}' \
  "${POLICY_API}/policies/${POLICY_ID}/approve"

Return 200 with a policy summary, policy ETag, and current draft validator where applicable. Relevant response fields include:

{
  "policy": {
    "id": "policy-1",
    "status": "approved",
    "policyState": "approved",
    "governedRevision": 1,
    "hasOpenDraft": false,
    "draftState": null
  }
}

Policy revalidates dependencies before creating the governed revision. Changed or unacknowledged findings can block approval. Approval queues durable asynchronous publication. It does not prove publication, consumer receipt, or downstream protection. Inspect the independent enforcementState and operation evidence. Operation inspection requires policy:audit. Approval capability alone does not grant that access.

POST /policies/{policy_id}/archive

Request removal of the approved policy’s published configuration. Use GET /policies/{policy_id}/operations to monitor that background removal. Confirm that the policy has a governed revision before selecting archive. Draft cancellation is a separate operation and does not withdraw governed protection. Require policy:archive. Send the latest policy ETag through If-Match, never the draft token.

The archive request accepts this reason field:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${POLICY_ETAG}" \
  --data '{"reason":"Approved retirement of the governed policy."}' \
  "${POLICY_API}/policies/${POLICY_ID}/archive"

Return 200 with a policy summary, deploymentId, and integer generation. The summary identifies the independent archiving protection state. Do not interpret the compatibility archive status as completed withdrawal. Record the returned generation for subsequent archive evidence or authorized retry. Use deploymentId to select the operation and generation to distinguish its work from later attempts.

Response Codes and Concurrency

The table lists possible failure status codes for each lifecycle operation:

401 identifies missing trusted identity. 403 identifies missing authority. 404 identifies missing policy or draft context. 428 identifies a missing required token. Draft commands normally return 409 for a changed head. Request-changes also returns 409 when the head is not in review. Submit and approve return 400 for a non-draft token. Concurrent policy/revision persistence can produce 412. Archive returns 400 for malformed policy tokens and 412 for stale versions.

409 can also mean invalid lifecycle state, blocking conflicts, or changed dependencies. 422 can contain body-schema errors or sanitized validation findings. Compile, submit, and approval validation failures can expose a supportReference. Refer to error handling for envelope variations.

These commands do not implement a general Idempotency-Key contract. After a timeout, inspect current policy and history before deciding whether to repeat. After a conflict, review changed evidence before issuing another command. Do not apply a fresh token to an old, unreviewed decision.

7.9 - 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.

7.10 - Product Retrieval and Compatibility Deployment

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.

Send the following headers when retrieving published consumer output:

curl --fail-with-body -i \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/product-policies/federated-guardrails"

Return 200 with ETag, Last-Modified, and Cache-Control headers. The response contains:

Illustrative response:

{
  "product_id": "federated-guardrails",
  "updated_at": "2026-10-29T12:00:00Z",
  "revision": 15,
  "version": 4,
  "fingerprint": "example-lineage-fingerprint",
  "content": {
    "entities": [],
    "warnings": [],
    "policies": {
      "templates": {},
      "staticPolicies": {},
      "templateLinks": []
    }
  }
}

A matching If-None-Match condition returns 304 with no body. The response supplies Last-Modified, but this operation does not evaluate If-Modified-Since. The fingerprint identifies contributing policy versions, rather than only comparing generated text. Background recompilation can change those versions without another human approval. The product revision and version identify aggregate output, not one policy’s governed revision. Use policy history to find an individual policy’s approved version and compilation minor.

Return 404 when no published output exists. Return 422 for an unsupported product type. Gateway identity and access failures can return 401 or 403.

Guardrails Receipt Boundary

When GUARDRAILS_CONSUMER_USERNAME is nonempty, only the exact trusted consumer identity records receipt evidence. The setting does not authenticate callers. The empty-string default accepts only requests with absent or empty identity, for anonymous compatibility. Named requests do not qualify under this default. Qualifying 200 and 304 responses can both record evidence. With a nonempty setting, anonymous reads and diagnostics under another identity do not qualify. Receipt does not prove activation or receipt by every target replica.

A qualifying consumer retrieval records receipt. No separate acknowledgement request is required. Successful retrieval alone does not establish eligibility. The receipt must match current publication targets and checksums, or exact current contributor lineage in a newer aggregate. Publication reaches Published. Publication plus qualifying receipt allows reconciliation to Enforced for Guardrails-only policies. Mixed policies also require Data protection evidence. Use Guardrails monitoring to check whether the consumer applies the retrieved configuration.

The chart maps apiService.environment.GUARDRAILS_CONSUMER_USERNAME through the API ConfigMap into the environment. Refer to Guardrails consumer evidence. The setting does not change gateway access rules.

POST /policies/{policy_id}/deploy

Retain this compatibility operation for eligible legacy approved policies. Do not use it to force publication of a governed revision. Governed delivery belongs to approval and background processing. The server rejects this operation when governed publication owns delivery.

Require policy:approve and a trusted caller identity. Policy forwards the caller’s bearer credential for request-driven Policy Integration Manager (PIM) writes. That caller also needs the applicable PIM permissions. Policy accepts the gateway’s deployment cookie fallback when no explicit authorization header exists. Do not send identity-forwarding headers or an actor in the body.

The route accepts the following path and query parameters:

This route does not require If-Match or a general Idempotency-Key. The body uses application/json. It extends the public compile request with these optional fields:

pimBindings requires an audit reason and cannot replace an existing ownership binding. Refer to reconciliation for governed ownership incidents. The public deployment schema does not accept a Secure Query-native variant. Use the deployed /doc document for the complete nested compile and native rule schemas.

Before running this compatibility-only request, prepare and review the complete deploy-request.json file. Set POLICY_ID to the eligible legacy policy’s identifier. Use the compile-body reference for its base fields and the additional deployment fields listed above. Do not pass the outer create-policy envelope from the worked lifecycle.

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @deploy-request.json \
  "${POLICY_API}/policies/${POLICY_ID}/deploy?reuse_existing=true"

Return 200 with plan, result, and nullable reconciliation. The last field can contain protected, unprotected, awaiting_protection, and unreadable resource-identifier arrays. These arrays report observed resource states, not confirmation that every intended target applies the configuration.

The following table summarizes compatibility deployment status codes and their meanings:

If the request times out, check policy detail and ask the PIM administrator whether the affected objects changed. Do not repeat deployment until the administrator checks for a partially applied request.

7.11 - Authoring Schema Operations

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 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.

Cedar is the policy language whose schema defines entity types, attributes, and actions. Schema responses describe allowed types and actions. They do not list discovered users, groups, or data locations. Use /catalog/principals and /catalog/resources to obtain the identifiers needed by compile requests. For actions, use the vocabulary required by that request field rather than copying a display label from another endpoint.

GET /schema/cedar