Skip to content

Authorization API Reference ​

POST /authz/check ​

Evaluate a permission

Use from a trusted application service to make a single authorization decision for a user and resource context. The caller must use a service-kind bearer token. Every non-platform (team-scoped) grant applies only to its matching active resource.team_id; team baselines are inherited by users with any unexpired group membership in that active team. Platform bindings with null team_id remain available without team membership, but an eligible member's applicable team deny still overrides a matching platform allow for that team's resource. A platform administrator without active membership does not inherit the baseline deny and retains independent platform grants. A requested :team permission without resource.team_id denies. A false condition excludes only that grant and, if nothing else matches, leaves reason no matching grant; an error evaluating any applicable condition fails the whole decision with reason condition_error. Explicit deny wins matching allows; there is no role/source priority. matched lists every applicable key that matched, sorted lexicographically. Set max_auth_age_seconds to require recent authentication and pass auth_time from the user's token; a missing, future, or stale auth_time returns allow=false with reason step_up_required.

Request body (application/json) ​

FieldTypeRequired
auth_timeintegerNo
contextobjectNo
max_auth_age_secondsintegerNo
permissionstringYes
subjectstringYes
json
{
  "auth_time": 1727712000,
  "context": {
    "resource": {
      "attrs": {
        "region": "us-east-1"
      },
      "owner_id": "01J8Z3OWNER000000000000001",
      "team_id": "01J8Z3TEAM000000000000001"
    }
  },
  "max_auth_age_seconds": 600,
  "permission": "orders:read:team",
  "subject": "01J8Z3USER000000000000001"
}

Responses ​

  • 200 — Successful response
json
{
  "allow": true,
  "matched": [
    "orders:read:team"
  ],
  "reason": "permission granted"
}

Errors ​

StatusCodeDetail
400subject is requiredInvalid Request
401a service subject is requiredUnauthorized
404the requested user was not foundNot Found
422permission must use resource:action:scope grammarInvalid Permission
500authorization service unavailableInternal Server Error

GET /authz/permissions/{userID} ​

List effective grants

Use from a trusted service to refresh a permission cache for one user. Send GET /authz/permissions/{userID}?version=2; the service-kind bearer token is required. Missing or non-2 versions return 400 rather than an unsafe flattened snapshot. The v2 response carries version, user_id, perm_ver, grants with optional condition and team_id, and optional RFC 3339 valid_until (the earliest future membership or binding expiry affecting grants). Platform grants omit team_id; scoped grants include a non-empty team_id. Clients must require response version=2 and all required v2 fields, strictly validate defined field and grant types/shapes, and ignore unknown additive fields at the snapshot or grant level. Unknown fields add no security semantics; future security-semantic changes require an explicit version. SDKs clamp cache expiry to valid_until.

Path parameters ​

ParameterDescription
userIDPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "grants": [
    {
      "key": "reports:read:any"
    },
    {
      "condition": "resource.attrs[\"region\"] == \"us-east-1\"",
      "key": "orders:read:team",
      "team_id": "01J8Z3TEAM000000000000001"
    }
  ],
  "perm_ver": 3,
  "user_id": "01J8Z3USER000000000000001",
  "valid_until": "2026-11-01T00:00:00Z",
  "version": 2
}

Errors ​

StatusCodeDetail
400version=2 is required; legacy snapshots are not supportedUnsupported Permission Snapshot Version
401authentication failedUnauthorized
404the requested user was not foundNot Found
500authorization service unavailableInternal Server Error