Policies

Providing the machine-readable policies that define the business aspects of API operations and how it is governed, breaking down the business and technical details of API operations in terms that help organize and make the governance of APIs approachable by business stakeholders and leadership.

Also known as: Policy, Governance Policies, Business Policies

Example

- type: X-Policies
  url: https://developers.example.com/policies

Standards

CNCF (graduated) Open Policy Agent (OPA)
CNCF Rego policy language
AWS / open source Cedar policy language
JSON Schema JSON Schema 2020-12
OASIS XACML 3.0
IETF RFC 6749 — OAuth 2.0 (scopes as policy attributes)
NIST NIST SP 800-162 — Attribute Based Access Control

Media Types

application/json — Policy data documents and decision logs (OPA input/result envelopes).
application/yaml — Common authoring format for policy bundles and config.
text/x-rego — Rego source files (de facto; .rego extension).

OpenAPI Expression

components.securitySchemes / security (OpenAPI 3.x) — OAuth 2.0 scopes act as coarse policy attributes that downstream PDPs can refine.
x-policy (Vendor extension) — Custom marker referencing a Rego/Cedar bundle that governs the operation.

Governance Rules

oas-security-defined (Spectral built-in) — Operations must reference a defined security scheme so policy enforcement can hook in.
operation-tag-defined (Spectral built-in) — Tags often drive policy scope (e.g., by domain or sensitivity).

Risk & Compliance

Compliance:

SOC 2 CC6.x — logical access controls implemented as auditable policy
ISO/IEC 27001 A.9 — access control policy and procedures
GDPR Art. 5 — purpose limitation and data minimisation as policy constraints
HIPAA 45 CFR §164.308 — administrative safeguards

Security: Without machine-readable policy, authorization logic is scattered through application code and gateways and cannot be audited or replayed. Centralize decisions in a PDP (OPA, Cedar) and emit decision logs for compliance evidence.

Tools

Open Policy Agent — Policy engine (Apache-2.0)
Conftest — Config / spec policy testing (Apache-2.0)
Cedar — Policy engine (Apache-2.0)
Styra DAS — OPA control plane
AWS Verified Permissions — Managed Cedar service
Permit.io — Policy-as-a-service

Suggested Metrics

policy_decision_count — Number of allow/deny decisions emitted by the PDP per unit time.
policy_deny_rate — Share of decisions that result in a deny; sudden swings indicate policy regression.
policy_evaluation_p95_ms — 95th-percentile latency of policy decisions; in-band policy must stay well below request budget.
policy_bundle_version_drift — Number of enforcement points running an outdated policy bundle.

Example Implementations

AWS — IAM policy documents and Verified Permissions (Cedar) for application-level authz.
GitHub — Fine-grained PAT permissions and organization policies governing API access.
Styra — Commercial control plane for Open Policy Agent and Rego policy distribution.