Px/

Quick Start

Get your first authorization decision running in minutes — choose your integration path below.

Edit this page on GitHub
Java / Spring Boot

Add the Maven dependency and annotate a controller method. Done.

Java / Quarkus

CDI interceptor — annotate any JAX-RS endpoint.

REST API directly

Use the HTTP API from any language with a Bearer token.

ABAC policies

Define attribute-based condition trees for fine-grained control.

Option A — Java SDK (Spring Boot, 3 steps)#

1. Add the dependency#

xml
<dependency>
  <groupId>io.gitlab.ctu-iotlab</groupId>
  <artifactId>com.authorization.core</artifactId>
  <version>0.1.5</version>
</dependency>

2. Configure application.properties#

properties
ctu.iotlab.resource-config.url=https://api.permix.dev
ctu.iotlab.resource-config.service-name=my-service
ctu.iotlab.resource-config.enabled=true
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://keycloak.example.com/realms/myrealm
bash
export ADMIN_CLIENT_ID=iotlab-admin
export ADMIN_CLIENT_SECRET=your-secret

3. Annotate a method#

java
@GetMapping("/invoices/{id}")
@Resource(
  name        = "invoice:read",
  displayName = "Read Invoice",
  defaultRoles = {"finance", "admin"}
)
public ResponseEntity<Invoice> getInvoice(@PathVariable String id) {
  return ResponseEntity.ok(invoiceService.findById(id));
}

On startup, the SDK registers invoice:read with Permix. On every call, it forwards the inbound Authorization header to POST /resources/access/check and returns 403 if the decision is {"authorized": false}.

Option B — REST API#

1. Get a token#

bash
export TOKEN=$(curl -s -X POST \
  https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token \
  -d "grant_type=client_credentials&client_id=my-client&client_secret=my-secret" \
  | jq -r .access_token)

2. Register a resource#

bash
curl -X POST https://api.permix.dev/api/v1/resources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "invoice:read",
    "displayName":  "Read Invoice",
    "serviceName":  "my-service",
    "defaultRoles": ["finance", "admin"]
  }'

3. Check access#

bash
curl -X POST https://api.permix.dev/api/v1/check \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject":  "user_123",
    "resource": "invoice:read",
    "action":   "read",
    "domain":   "tenant_prod"
  }'

Response:

json
{
  "decision":        "allow",
  "matched_rule_id": "3f7a1b2c-...",
  "reason":          "RBAC policy matched"
}

Option C — ABAC with attribute conditions#

Add a condition-based policy alongside the RBAC rule:

bash
curl -X POST https://api.permix.dev/api/v1/abac/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":     "Finance only",
    "resource": "invoice:read",
    "effect":   "allow",
    "priority": 10,
    "rule_data": {
      "type":      "CONDITION",
      "attribute": "user.department",
      "operator":  "eq",
      "value":     "Finance"
    }
  }'

Then include attributes in the check call:

bash
curl -X POST https://api.permix.dev/api/v1/check \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "subject":  "user_123",
    "resource": "invoice:read",
    "action":   "read",
    "domain":   "tenant_prod",
    "attributes": {
      "user": { "department": "Finance" }
    }
  }'

Verify the health check#

bash
curl https://api.permix.dev/healthz/ready
# {"status":"ok","checks":{"database":"ok","casbin":"ok"}}

Next steps#