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.