API Reference

All authenticated endpoints require a valid Bearer JWT in the Authorization header. SaaS admin endpoints use X-Admin-Api-Key instead.

Health probes#

No authentication required. Designed for Kubernetes liveness and readiness probes.

GET /healthz/live#

Returns 200 OK if the service process is running. No dependency checks.

{ "status": "ok" }

GET /healthz/ready#

Checks PostgreSQL and Casbin. Returns 200 when healthy, 503 when degraded.

{
  "status": "degraded",
  "checks": {
    "database": "unavailable",
    "casbin": "ok"
  }
}

Decision API#

POST /api/v1/check#

Combined RBAC + ABAC decision endpoint. Both engines are evaluated; ABAC deny at high priority wins.

Request:

{
  "subject":  "user_123",
  "resource": "invoice:read",
  "action":   "read",
  "domain":   "tenant_prod_42",
  "attributes": {
    "user":     { "department": "Finance", "clearance_level": 3 },
    "resource": { "classification": "internal" }
  }
}

Response 200:

{
  "decision":        "allow",
  "matched_rule_id": "3f7a1b2c-...",
  "reason":          "ABAC policy 'Finance read invoices' matched"
}

POST /api/v1/resources/access/check#

Legacy RBAC-only check used by the Java SDK @Resource interceptor.

Resource management#

POST /api/v1/resources#

Register a single resource (called automatically by the Java SDK on startup).

{
  "name":         "invoice:read",
  "displayName":  "Read Invoice",
  "serviceName":  "invoice-service",
  "defaultRoles": ["finance", "admin"]
}

POST /api/v1/resources/list#

Bulk register multiple resources in one call.

GET /api/v1/resources#

List all resources scoped to the caller's tenant.

GET /api/v1/resources/{id}/policies#

Get Casbin RBAC policies for a specific resource.

POST /api/v1/resources/policies#

Create a Casbin RBAC rule: (sub, dom, obj, act) → allow/deny.

PUT /api/v1/resources/policies#

Update an existing rule.

DELETE /api/v1/resources/policies#

Remove a rule.

ABAC policy management#

POST /api/v1/abac/policies#

Create an ABAC policy. See ABAC docs for condition tree syntax.

Request:

{
  "name":      "Finance read invoices",
  "resource":  "invoice:read",
  "effect":    "allow",
  "priority":  10,
  "rule_data": {
    "type":      "CONDITION",
    "attribute": "user.department",
    "operator":  "eq",
    "value":     "Finance"
  }
}

GET /api/v1/abac/policies#

List policies. Filter by ?resource=invoice:read or ?effect=deny.

GET /api/v1/abac/policies/{id}#

Get a single policy by ID.

PUT /api/v1/abac/policies/{id}#

Update a policy (resource field is immutable after creation).

{ "enabled": false, "priority": 5 }

DELETE /api/v1/abac/policies/{id}#

Soft-delete (sets deleted_at, record retained).

ABAC policy response schema#

{
  "id":          "uuid",
  "tenant_id":   "string",
  "name":        "string",
  "description": "string | null",
  "resource":    "string",
  "effect":      "allow | deny",
  "format":      "json | casbin",
  "rule_data":   {},
  "priority":    0,
  "enabled":     true,
  "created_by":  "string",
  "created_at":  "2026-05-10T08:00:00Z",
  "updated_by":  "string | null",
  "updated_at":  "2026-05-10T09:00:00Z | null"
}

SaaS admin routes#

Require X-Admin-Api-Key: $ADMIN_KEY (or Authorization: Bearer $ADMIN_KEY).

POST /admin/tenants#

Create tenant. Returns one-time bootstrapKey.

{ "name": "Acme Corp", "slug": "acme" }

Response:

{ "id": "tenant_abc", "name": "Acme Corp", "slug": "acme", "bootstrapKey": "bk_live_xxx" }

GET /admin/tenants#

List all tenants.

POST /admin/tenants/{id}/identity-providers#

Register an OIDC IdP for a tenant.

{
  "issuer_url": "https://idp.example.com/realms/acme",
  "jwks_uri":   "https://idp.example.com/realms/acme/.well-known/jwks.json",
  "claim_config": {
    "roles_claim": "realm_access.roles",
    "domain_claim": "dom",
    "admin_domain_claim": "adm"
  }
}

GET /admin/tenants/{id}/identity-providers#

List IdPs for a tenant.

DELETE /admin/tenants/{id}/identity-providers/{idpId}#

Remove an IdP.

Error format#

{
  "error":   "VALIDATION_ERROR",
  "message": "missing required fields",
  "details": { "missing_fields": ["resource", "effect"] }
}