Introduction

Permix is a Go-based, dual-mode (SaaS + self-hosted) policy engine combining RBAC, ABAC, JWT validation, and multi-tenant management.

Edit this page on GitHub

Permix is a single-binary Go service that gives engineering teams a unified control plane for authorization decisions. It combines Casbin RBAC, a custom ABAC attribute engine, provider-agnostic JWT validation, and full multi-tenant SaaS infrastructure behind one low-latency decision API.

Quick Start

Make your first access-check call in under 5 minutes.

ABAC Policies

Define attribute-based rules with a flexible JSON condition tree engine.

API Reference

Full endpoint listing with request and response shapes.

Deployment

Environment variables, Kubernetes health probes, and Docker Compose.

Capabilities#

Feature	Description
RBAC via Casbin	Role → domain → resource → action rules managed through a clean REST API
ABAC policy engine	JSON condition trees with AND/OR logic, priority ordering, and enable/disable toggles
Provider-agnostic JWT	Validates RS256 and ES256 tokens from any OIDC provider — Keycloak, Auth0, Okta, or your own
Per-issuer ValidatorCache	SaaS mode caches JWKS validators per issuer for zero-overhead multi-IdP resolution
Multi-tenant SaaS	Full tenant provisioning, identity provider management, and tenant-scoped data isolation
Service API keys	Service-to-service authentication without OAuth2 client credentials
Java SDK	Spring Boot and Quarkus integration via `@Resource` annotation — zero boilerplate
Health probes	`/healthz/live` and `/healthz/ready` check database and Casbin engine readiness

Deployment modes#

The service boots into one of two modes set by the MODE env var (default: selfhost).

	`selfhost`	`saas`
JWT validation	Single global JWKS URI	Per-tenant `ValidatorCache`
Tenant isolation	Single implicit tenant	Full multi-tenant DB scoping
Admin auth	Admin API key header	`X-Admin-Api-Key` header
Identity providers	Configured via env vars	Managed via `/admin/tenants/{id}/identity-providers`
Tenant management	N/A	Full CRUD at `/admin/tenants`

Core concepts#

Concept	Description
Subject	Identity making the request — JWT `sub`, user ID, or service account
Resource	Named entity being accessed (`invoice:read`, `project:deploy`, etc.)
Action	Operation attempted on a resource (`read`, `write`, `approve`, `deploy`)
Domain	Tenant or organisation scope for Casbin multi-tenant isolation
RBAC Policy	Casbin rule: `(role, domain, resource, action) → allow/deny`
ABAC Policy	JSON condition tree evaluated against namespaced request attributes
Service API Key	Long-lived credential for service-to-service calls without OAuth2

API surface#

rounded-md border px-1.5 py-0.5 font-mono text-[0.82em]

# Health probes — no auth
GET  /healthz/live
GET  /healthz/ready

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

# Resource management (JWT required)
POST   /api/v1/resources
POST   /api/v1/resources/list
GET    /api/v1/resources
GET    /api/v1/resources/{id}/policies
POST   /api/v1/resources/policies
PUT    /api/v1/resources/policies
DELETE /api/v1/resources/policies

# ABAC policy management (JWT required)
POST   /api/v1/abac/policies
GET    /api/v1/abac/policies
GET    /api/v1/abac/policies/{id}
PUT    /api/v1/abac/policies/{id}
DELETE /api/v1/abac/policies/{id}

# Service API keys (JWT required)
POST   /api/v1/service-api-keys
GET    /api/v1/service-api-keys
DELETE /api/v1/service-api-keys/{id}

# SaaS admin (X-Admin-Api-Key required)
POST   /admin/tenants
GET    /admin/tenants
POST   /admin/tenants/{id}/identity-providers
GET    /admin/tenants/{id}/identity-providers
DELETE /admin/tenants/{id}/identity-providers/{idpId}