Understand Policy

• 1: Policy Overview
• 1.1: Role-Based Access Control and Artificial Intelligence Policies
• 2: States and Revisions
• 3: Roles and Permissions
• 4: Classifications, Principals, and Methods
• 5: Validation and Review Decisions
• 6: Policy Terminology

1 - Policy Overview

Policy combines guided authoring, review decisions, governed revisions, and delivery evidence. Refer to Understand Policy for the canonical conceptual references. Refer to Start here for an ordered learning path.

Key Capabilities

Policy supports the following responsibilities:

• Find policies and inspect available detail and history through Policy Library.
• Author Data protection or artificial intelligence (AI) policies with lane-specific inputs.
• Save proposed work separately from the current governed revision.
• Submit, request changes, and approve with the appropriate authority.
• Publish approved artifacts and inspect target-specific delivery evidence.
• Refresh approved compilation output through background processing.

Policy Release Highlights

Supported authoring choices and available interface actions depend on your release and authority. Use the corresponding task guide rather than inferring support from a conceptual example. The API reference distinguishes operation contracts from interface presentation.

Documented Use Cases

Refer to use cases for author, reviewer, operator, and integration journeys.

Supported Platforms

The deployment guides target Kubernetes with the required Protegrity platform integrations. They do not establish support for arbitrary standalone platform combinations.

System Requirements

Operators need the release’s platform, storage, gateway, identity, and integration prerequisites. PostgreSQL runs inside the Policy stack. Authors and reviewers need the capabilities for their assigned tasks. Refer to installation and access preparation.

Architecture

Refer to Architecture for component responsibilities and delivery boundaries.

Definitions

Use these references for shared definitions:

• States and revisions
• Roles and permissions
• Classifications, principals, and methods
• Role-based access control and AI policies
• Policy terminology

1.1 - Role-Based Access Control and Artificial Intelligence Policies

Role-based access control (RBAC) governs access to Policy operations. An authored artificial intelligence (AI) policy governs a different concern: runtime behavior for the selected principals and classifications. Here, runtime means downstream processing of requests or data, not administration of the Policy service. Do not treat these two permission systems as interchangeable.

RBAC in Policy

The platform authenticates users through its supported gateway integration. Policy maps trusted authorities to command capabilities. Editing and rollback also require applicable policy access grants.

The policy_author bundle does not provide review or approval authority. An owner grant does not add either capability. Different authenticated users can therefore perform the author and reviewer responsibilities. This capability separation does not itself enforce mandatory two-person approval.

Refer to roles and permissions for the canonical role and capability tables. Refer to API authentication for the request-level identity contract.

AI Policy in Policy

AI authoring captures classification and principal-specific runtime permissions. Its permissions matrix describes the selected principals’ allowed behavior. It does not assign those principals administrative roles in Policy.

For example, a principal can receive a runtime unprotect permission. Unprotect means allowing supported runtime access to protected content. It does not remove a governed policy. That permission does not allow the principal to submit or approve a Policy draft. Likewise, a Policy approver does not automatically receive runtime unprotect access.

Preview output, saved content, approval, and consumer receipt remain distinct checkpoints. A delivered Federated Guardrails artifact does not prove execution against real traffic. Refer to validation and review decisions and delivery verification.

Verification

Verify product access and authored runtime permissions independently. Refer to authoring procedures for the selected lane. Refer to lifecycle and governance for the review handoff.

2 - States and Revisions

A policy can have governed content and an open replacement draft simultaneously. Saving that replacement does not make it the approved policy. Publication and observed protection remain separate from both authoring and approval.

Three Independent Questions

The following table distinguishes the questions answered by draft, governance, and delivery evidence:

Before first approval, no governed revision or protection evidence may exist. An empty protection value does not mean protection succeeded or failed. Do not derive these independent concerns from one displayed status.

Drafts and Saved Snapshots

The policy identifier remains stable across its lifecycle. A draft identifies proposed work for that policy. Each successful save creates a retained snapshot of that work. Repeated saves do not create repeated governed revisions. The draft head is its current saved snapshot, not the governed revision. A snapshot records saved content. The draft’s head changes when later work supersedes it.

Submission puts the current proposal into review. A request for changes returns editable work with the reviewer’s reason. The author can correct that proposal and submit it again. Reviewing a draft does not publish its contents.

Governed Revisions and Compilation Minors

Approval creates a governed revision from the exact reviewed draft. It also starts asynchronous delivery work. A later authored replacement must pass through the review workflow again.

Automatic recompilation serves a different purpose. It recompiles approved intent against fresh context without requiring author edits. Changed output creates a compilation minor under the governed revision. Approved intent means the reviewed classifications, principals, methods, and permission selections. A compilation minor changes generated target configuration, not those authored selections. It preserves the original approval identity and leaves open drafts unchanged. Unchanged output creates no compilation minor or publication work.

For example:

1. Alex saves and submits a draft. The draft remains proposed work until an authorized approval succeeds.
2. Morgan approves the current submission. Policy creates the first governed revision and queues publication.
3. A later automatic cycle detects changed compilation output. Policy records a compilation minor and queues new delivery work.
4. Alex edits the authored policy. The new draft remains separate from the governed revision and its compilation minors.

Refer to automatic recompilation for scheduling, failures, and observation.

Delivery Generations and Evidence

A deployment generation identifies a particular publication or withdrawal operation. A retry continues retained work for that generation. It does not approve new authored content or substitute a corrected draft. The deployment identifier selects the retained operation. Its generation distinguishes successive publication or withdrawal operations for the policy. Inspect operation history rather than deriving either value from the governed revision number.

For Data protection, verify the expected location scope and positive protection observations. For Federated Guardrails, a consumer receipt records retrieval of the currently generated configuration. A receipt does not prove execution against real traffic or activation by every replica. A policy using both targets needs complete Data observations and the matching Guardrails receipt.

Publication failure does not undo the approval that created the governed revision. Withdrawal can also remain incomplete after an archive request succeeds. Do not treat archive acceptance as completed deprotection.

Concurrency Tokens Identify Different Resources

Application programming interface (API) clients must retain server-issued validators. An entity tag (ETag) is an opaque validator for one resource version. Send the exact value, including quotes, in the operation’s required If-Match header. It is not an authentication token, policy identifier, or interchangeable revision number.

The table identifies each resource’s validator and the distinction API clients must preserve:

The API reference defines each operation’s exact token and error contract. Continue with lifecycle and governance for the author and reviewer tasks.

3 - Roles and Permissions

Authentication establishes who is making a request. Authorization determines whether that identity can perform the requested operation. Some commands also require access to the particular policy. A command capability answers whether an identity may perform an operation at all. A policy access grant answers whether that operation may affect this specific policy. Commands that require both checks must satisfy both.

Responsibilities Are Not New Roles

An author prepares and submits proposed work. A reviewer inspects a submission and can request changes with the required authority. An approver accepts the reviewed content with approval authority. An operator observes delivery and performs specifically authorized recovery tasks.

One person can hold multiple responsibilities. Different users can also perform them with separate authenticated accounts. The capability model does not itself enforce mandatory two-person approval. There is no separate policy_reviewer role in the role bundles below.

Product Role Bundles

The following table summarizes each product role bundle and its key limitation:

Platform permissions can map to capabilities separately from these role bundles. Their membership does not necessarily match the product bundles exactly. Ask the platform administrator to verify the effective authorities for your task. Unknown authorities do not create capabilities. An authority is a permission asserted by the trusted platform gateway. It is not a request field that clients may choose for themselves.

Command Capabilities

Use this table to identify the capability and policy boundary for each task:

Retry authority follows the retained operation. Publishing retry requires approval authority. Withdrawal retry requires archive authority. Refer to recovery and reconciliation for the complete operation-specific rules.

Policy Access Grants

An owner or editor grant determines access to particular authored work. It does not create review, approval, archive, or system configuration capabilities. An author role also does not automatically grant edit access to every policy. For example, policy:edit without an applicable owner/editor grant does not authorize an existing-policy edit. An owner grant without policy:approve does not authorize approval.

Refer to policy access management for grant changes. Do not remove the last active owner during routine access maintenance. Administrator recovery is a separate audited path, not an ordinary grant substitute.

Identity and Downstream Access

Use the supported platform sign-in or gateway authentication path. Policy records the authenticated actor. Clients must not impersonate another reviewer. Do not supply submittedBy or approvedBy as a workaround.

Policy authority does not automatically create permission in a downstream system. An operator may need separate integration and target access. Refer to security settings and API authentication.

Continue with lifecycle and governance.

4 - Classifications, Principals, and Methods

Authoring combines the data or runtime scope with intended principals and permissions. Catalog choices have operational meaning. They are not interchangeable display labels.

Classifications and Scope

A classification identifies a category of discovered data. For Data protection, its resolved locations determine where protection applies. Review that scope before submission, particularly after catalog changes. The same display name does not prove the same current location set. Scope is the resolved set of locations or runtime subjects to which the selected inputs apply. Record identifiers and representative locations, not just a classification’s display name.

An empty selection and an unresolved classification are different problems. An empty selection supplies no classification. An unresolved classification supplies an identifier that current discovery cannot match to the required input. Correct the selected input when it is wrong. Ask an operator to inspect discovery when expected catalog data is missing.

Principals and Permissions

A principal identifies an intended runtime subject, such as a configured group. Select it from the available catalog and verify its intended membership. Do not confuse a policy’s runtime principals with the users administering Policy.

For example, an application group may receive an unprotect permission. That permission does not allow the group to approve Policy drafts. Conversely, approval authority does not automatically grant runtime data access.

Protection Methods and Authoring Lanes

Data authoring captures protection choices supported by the selected release and target. Artificial intelligence (AI) authoring uses its own principal-permission matrix. Do not infer that every method listed in a catalog supports both lanes. Do not treat hidden, unsupported, or unavailable choices as tutorial prerequisites.

Preview helps inspect target-specific output. Saving retains authored inputs, including supported incomplete work. Submission and approval require current validation and the appropriate review decisions.

Changing Context

Discovery, configured identities, and native target inventory can change over time. Policy therefore validates current context during governance operations. Automatic recompilation can also generate updated artifacts from approved intent. Neither mechanism authorizes silently changing an author’s proposed policy.

Continue with Data and AI authoring or validation and review decisions.

5 - Validation and Review Decisions

Each checkpoint answers a different question about a policy. A successful earlier checkpoint does not guarantee success at the next one.

Checkpoint Meanings

The following table explains what each checkpoint establishes and what to verify next:

Blocking and Reviewable Findings

Some findings require correction before the operation can continue. Other findings permit an explicitly recorded review acknowledgement. An acknowledgement records an authorized acceptance of a specifically reviewable finding. It does not suppress validation, widen permissions, or override a blocking finding. Use the returned conflict identifiers and the current operation contract. Do not acknowledge every finding merely to make a request succeed.

Review notes explain an approval. A request-changes reason explains what the author must correct. Neither text field replaces a missing capability or stale concurrency token.

Fresh Validation and Stale Work

Current dependencies can change after a preview or earlier save. That context includes discovered locations, identity metadata, and current native target inventory. Submission and approval therefore validate current inputs and governed context. A reviewer must load the submitted draft and its current validation results before approving.

If a command reports changed work, refresh the policy and review the new content. Do not blindly replace the token and replay a consequential decision. Refer to API error handling.

Diagnostics and Escalation

An error can provide a support reference without disclosing restricted diagnostics. An ordinary author may need an authorized operator to inspect that reference. Record the operation, policy identifier, time, and safe error details. Never include access tokens or sensitive payload values in a support request. The reference identifies retained evidence. It neither contains that evidence nor grants permission to read it.

Refer to diagnostics for evidence collection and access boundaries. Continue with lifecycle and governance.

6 - Policy Terminology

Policy uses different records for authored work, approved content, and target delivery. Similar names do not make those records interchangeable. This reference explains the distinctions used in task instructions and error messages.

Authoring and Governance

The following table defines terms for authoring and governance:

For example, saving a corrected draft changes proposed work. Approval creates governed content. Automatic recompilation can then change generated output without another author edit. Refer to states and revisions.

Identity and Request Evidence

The following table defines identity and request-evidence terms:

An application programming interface (API) request can require authentication, a command capability, a policy grant, and a resource validator. Each satisfies a different condition. Refer to roles and permissions and API authentication.

Compilation, Delivery, and Protection

The following table defines compilation, delivery, and protection terms:

Refer to background processing and delivery verification.

Ownership and Recovery

The following table defines ownership and recovery terms:

For recovery actions and authority requirements, use the recovery directory. For installation limitations, consult known issues.