ABAC Policies

What is a policy?

A policy is a rule the engine evaluates every time a user attempts an action. It has three parts:

1. Matching — does this policy apply to this resource and action? Determined by resource_pattern and actions.
2. Conditions — given that it applies, are the extra conditions met? (user role, IP, time of day, custom attributes, etc.)
3. Effect — if everything matches, does the policy allow or deny access?

Every policy belongs to a tenant_id. It can optionally be scoped to a specific application via application_id.

Creating a policy

POST /api/v1/tenants/{tenant_id}/policies

{
  "name":             "admin-full-access",
  "display_name":     "Full Admin Access",
  "description":      "Ops team only",
  "effect":           "allow",
  "priority":         100,
  "resource_pattern": "users:*",
  "actions":          ["read", "write", "delete"],
  "conditions": {
    "subject.roles": { "in": ["admin"] }
  },
  "status": "active"
}

Fields

resource_pattern

The engine compares resource_pattern against the resource type in the evaluation context. There are exactly four matching forms:

resource_pattern does not support ?, character ranges, or advanced glob syntax — only these four forms. A pattern like "user*" (no : or /) only matches the literal string "user*".

actions

A policy applies to an action if any of these is true:

• actions is an empty array ([]) → applies to any action.
• actions contains "*" → applies to any action.
• actions contains the exact action string (case-sensitive).

Actions are arbitrary strings. The system imposes no fixed vocabulary — you define what strings you use ("read", "publish", "impersonate", etc.) both when creating policies and when calling the evaluate endpoint.

Conditions

The conditions field is a JSON object where each key is a context field path and its value is an object with one or more operators. All conditions are evaluated with AND — every one must pass for the policy to fire.

// Canonical form: field → { operator: value }
{
  "subject.roles":  { "in": ["admin", "auditor"] },
  "environment.ip": { "in_cidr": "10.0.0.0/8" },
  "environment.hour": {
    "gte": "09",
    "lte": "17"
  }
}

// Shorthand: a direct value is treated as "equals"
{
  "subject.id": "some-uuid"
}

Multiple operators on the same field are also ANDed together.

Available context fields

SUBJECT — the authenticated user

RESOURCE — the resource being acted on

ENVIRONMENT — request context

ACTION — the attempted action

Operators

Condition examples

Only users with role admin or auditor:

{
  "subject.roles": { "in": ["admin", "auditor"] }
}

Internal network only, on weekdays:

{
  "environment.ip":  { "in_cidr": "10.0.0.0/8" },
  "environment.day": { "in": ["monday","tuesday","wednesday","thursday","friday"] }
}

Multiple operators on one field (all must pass):

{
  "environment.hour": { "gte": "09", "lte": "17" }
}

Custom user attributes:

{
  "subject.department":      { "equals": "finance" },
  "subject.clearance_level": { "gte": 3 },
  "environment.ip":          { "in_cidr": "10.0.0.0/8" }
}

Multiple CIDR ranges:

{
  "environment.ip": {
    "in_cidr": ["192.168.0.0/16", "172.16.0.0/12", "10.0.0.0/8"]
  }
}

Evaluation engine

When a client requests access, the engine runs this exact algorithm:

1. Load active policies. Fetch all policies for the tenant with status = active and deleted_at IS NULL whose resource_pattern and actions match the context resource and action.
2. No policies found → default deny. Response includes "reason": "No matching policy found (default deny)". The system is deny-by-default: if nothing explicitly allows, access is denied.
3. Sort by priority descending. Higher number is evaluated first. Equal-priority policies have no guaranteed relative order.
4. Evaluate conditions. For each policy in order: check that all conditions pass (AND). If any condition fails, that policy is skipped and the engine moves to the next.
5. First Deny wins immediately. If a policy matches and its effect is deny, evaluation stops right there. No further policies are checked.
6. Allow is recorded but does not stop evaluation. If a policy matches and is allow, it's added to matched_policies and the engine continues. A Deny policy later in the sorted list can still win.
7. Final result. After the loop: if at least one Allow matched (and no Deny was hit), allowed: true. If nothing matched at all, allowed: false (default deny).

Key rule: Deny always wins over Allow. To block an exception, give the Deny a higher priority than the Allows you want it to override.

Evaluation response

{
  "allowed": true,
  "effect": "allow",
  "matched_policies": [
    {
      "policy_id":   "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "policy_name": "admin-full-access",
      "effect":      "allow",
      "priority":    100
    }
  ],
  "reason": null
}

Evaluating a context

Send a complete context to the evaluate endpoint. You construct this in your backend on every access check.

POST /api/v1/tenants/{tenant_id}/policies/evaluate

{
  "subject": {
    "id":          "uuid-of-the-user",
    "tenant_id":   "uuid-of-the-tenant",
    "roles":       ["admin", "viewer"],
    "groups":      ["ops-team"],
    "permissions": ["users:read", "users:write"],
    "attributes":  { "department": "engineering" }
  },
  "resource": {
    "resource_type": "user",
    "resource_id":   "uuid-of-the-resource",
    "owner_id":      "uuid-of-the-owner",
    "tenant_id":     "uuid-of-the-tenant",
    "attributes":    { "sensitivity": "high" }
  },
  "action": "write",
  "environment": {
    "ip_address":  "10.0.0.42",
    "user_agent":  "Mozilla/5.0 ...",
    "time":        "2026-06-24T14:30:00Z",
    "attributes":  { "country": "MX" }
  }
}

All fields inside resource and environment are optional. If time is omitted it defaults to the current server time.

Endpoints

Full examples

Full access for superadmins

{
  "name":             "superadmin-all",
  "effect":           "allow",
  "priority":         1000,
  "resource_pattern": "*",
  "actions":          ["*"],
  "conditions": {
    "subject.roles": { "in": ["superadmin"] }
  }
}

Read-only on weekdays

{
  "name":             "read-only-weekdays",
  "effect":           "allow",
  "priority":         50,
  "resource_pattern": "*",
  "actions":          ["read"],
  "conditions": {
    "environment.day": {
      "in": ["monday","tuesday","wednesday","thursday","friday"]
    }
  }
}

Finance reports — scoped by department and seniority

{
  "name":             "finance-reports-senior",
  "effect":           "allow",
  "priority":         200,
  "resource_pattern": "reports/finance/*",
  "actions":          ["read", "export"],
  "conditions": {
    "subject.department":      { "equals": "finance" },
    "subject.clearance_level": { "gte": 3 },
    "environment.ip":          { "in_cidr": "10.0.0.0/8" }
  }
}

Block delete for contractors

{
  "name":             "block-delete-contractors",
  "effect":           "deny",
  "priority":         800,
  "resource_pattern": "*",
  "actions":          ["delete"],
  "conditions": {
    "subject.groups": { "in": ["contractors"] }
  }
}

Testing a new role before going live

{
  "name":             "new-role-experiment",
  "effect":           "allow",
  "priority":         10,
  "resource_pattern": "documents:*",
  "actions":          ["read"],
  "conditions": {
    "subject.roles": { "in": ["new-experimental-role"] }
  },
  "status": "testing"
}