ACL and Permissions

Overview

ACL (Access Control List) in Oblax is a route-based permission system. Each ACL rule maps an HTTP method and route pair to a set of allowed token types. When a request hits your API, the platform checks the ACL rules to determine whether the caller’s token has permission to access that endpoint.

ACL rules use an HTTP-key-based identity strategy. Each rule is identified by a combination of HTTP method and route path, stored as a JSON file in your local /app/acl/ directory.

How ACL Works

Every API request carries a JWT. The platform extracts the token’s realm and role claims, then checks the ACL rules for the requested route. If a matching rule exists and the token’s claims satisfy the rule’s conditions, the request is allowed. If no rule matches or the claims do not satisfy the conditions, the request is rejected with a 403 Forbidden response.

Request → JWT → ACL Lookup → Allow / Deny

ACL Rule Identity

Each ACL rule is identified by an HTTP method and route pair:

<method>@<route>

Examples:

post@/api/v1/users
get@/api/v1/users
get@/api/v1/users/:id
delete@/api/v1/users/:id

On the filesystem, this maps to a normalized JSON file:

/app/acl/
  post_api_v1_users.json
  get_api_v1_users.json
  get_api_v1_users_-id.json
  delete_api_v1_users_-id.json

Normalization rules:

• @ becomes _
• / becomes _
• : becomes -
• File always ends in .json

Creating ACL Rules

Use the CLI to initialize and push ACL rules:

obx app acl init

This creates a template file in /app/acl/. Edit the file to define which token types can access the route, then push it to the platform:

obx app acl push post@/api/v1/users

You can also push rules directly by specifying the method and route:

obx app acl push --data @post_api_v1_users.json

ACL and Realms

ACL rules work closely with realms. A realm defines the access scope of a token, and ACL rules determine which realms can access which routes. For example, you might configure a webapp realm for end users and an admin realm for administrators, then create ACL rules that restrict certain endpoints to the admin realm only.

{
  "method": "post",
  "route": "/api/v1/admin/users",
  "allowedRealms": ["app:admin"],
  "allowedRoles": ["admin"]
}

ACL and JWT Roles

ACL rules can filter by the role claim in the JWT. This lets you create fine-grained permissions that distinguish between different types of users within the same realm.

Where to next