Policies

A policy grants capabilities to a principal. Policies are the mechanism for defining authorization.

Policy Structure

A policy specifies:

  • principal: Who this policy applies to
  • capabilities: What they're allowed to do
  • expires_at: When the policy expires (optional)
  • created_at: When the policy was created
  • metadata: Custom attributes (optional)

Simple Policy

principal: alice capabilities: - invoice.read - invoice.view - dashboard.view

Alice can read and view invoices, and view the dashboard.

Policy with Expiration

principal: bob capabilities: - report.export expires_at: 2026-12-31

Bob can export reports until the end of 2026.

Multiple Policies

A principal can have multiple policies. All applicable policies are considered during authorization.

Policy 1: alice can [invoice.read, invoice.view] Policy 2: alice can [dashboard.view] Policy 3: alice can [report.export] until 2026-06-30

Alice's capabilities are the union of all her policies:

  • invoice.read ✓
  • invoice.view ✓
  • dashboard.view ✓
  • report.export ✓ (until June 30)

Policy Versioning

Policies are versioned. Every change to a policy creates a new version.

This allows you to:

  • Audit policy history
  • See what permissions existed at any point
  • Revert to previous versions if needed

Policy Lifecycle

Create

A policy is created for a principal.

Active

The policy is in effect. The principal has the granted capabilities.

Modify

A policy can be modified (e.g., add/remove capabilities). The modification creates a new version.

Suspend

A policy can be suspended. The principal no longer has the granted capabilities.

Expire

A policy automatically expires at its expiration time (if set).

Best Practices

1. Least Privilege

Grant only the capabilities needed for the job.

Instead of: [invoice.read, invoice.refund, invoice.void, invoice.delete] Use: [invoice.read]

2. Use Expiration

Set expiration dates on temporary authority.

Principal: contractor-june Capability: [api.write] Expires: 2026-06-30

3. Separate Environments

Use separate principals or policies for development, staging, and production.

alice-dev can [api.write, database.modify] alice-prod can [api.read]

4. Review Regularly

Audit who has what permissions regularly. Use evidence to identify unused permissions.

Policy Review & Audit

Use evidence to review policy effectiveness:

  • Are all granted capabilities being used?
  • Are there denied requests that should be allowed?
  • Do policies match the principle of least privilege?

Next Steps