Core Concepts

Identity vs Principal vs Authority

The core insight of AuthBoundry is the separation between three concepts:

1. Identity

Identity is who you are. It comes from your identity provider: a GitHub user, an OAuth token, a service principal.

Your identity provider controls this. You don't manage identity in AuthBoundry—you receive it from your identity provider.

2. Principal

A principal is an authority-bearing subject in your system. It's a first-class entity that can hold permissions.

One identity can map to multiple principals. For example:

  • A GitHub user (identity) might have two principals: one for development and one for production deployments
  • A service account (identity) might have one principal

3. Authority

Authority is what a principal is allowed to do. It's defined by policy and evaluated at every boundary.

Authority is your responsibility. You manage it in AuthBoundry.

Sessions & Claims

Session

A session represents an authenticated instance of an identity. Sessions are time-bound and can be revoked.

When you log in, you create a session. When you log out or your session expires, the session ends.

Claims

Claims are assertions from your identity provider about the authenticated identity.

Examples:

Claims are immutable and come from your identity provider. They inform policy decisions but do not determine authority on their own.

Capabilities

A capability is a specific action that an application can perform.

Examples:

  • invoice.read
  • invoice.refund
  • document.delete
  • api.write

Capabilities are explicit and enumerable. AuthBoundry discovers them from your application's routes and handlers.

Policies & Delegation

Policy

A policy grants capabilities to a principal.

Example policy:

principal: user_alice capabilities: [invoice.read, invoice.approve] expires_at: 2026-12-31

Policies are versioned and audited. You can see what permissions existed at any point in time.

Delegation

Delegation is temporary authority transfer.

If user_alice wants user_bob to have authority she has, she can delegate it:

  • Alice delegates invoice.refund to Bob
  • Bob can now refund invoices
  • When the delegation expires or is revoked, Bob can no longer refund invoices

Delegations are explicit, time-bound, and audited.

Authorization & Evidence

Authorization

Authorization is the process of evaluating whether a principal is allowed to perform a capability.

When your application receives a request:

  1. Your app asks AuthBoundry: "Is this principal allowed to perform this capability?"
  2. AuthBoundry evaluates policies and delegations
  3. AuthBoundry returns: ALLOW or DENY

Evidence

Evidence is an immutable record of every authorization decision.

For each decision, AuthBoundry records:

  • Who requested it (principal_id)
  • What they requested (capability)
  • What the decision was (ALLOW or DENY)
  • Why (which policy granted it, which policy denied it)
  • When (timestamp)

Evidence is queryable and immutable. You can audit the entire history of authorization decisions.

Multi-Tenancy

AuthBoundry is designed for multi-tenant applications. Each tenant has:

  • Isolated principals
  • Isolated policies
  • Isolated delegations
  • Isolated evidence

Cross-tenant isolation is enforced at every boundary. A principal in tenant A cannot access resources in tenant B.

Next Steps

  • Read Principals to understand how to define authority-bearing subjects
  • Read Policies to learn how to grant capabilities
  • Read Authorization to understand how decisions are evaluated