Realms

Overview

A realm is an access scope that partitions a project into isolated security domains. Every JWT carries a realm claim that identifies which scope the token operates in. ACL rules use realm values to determine which tokens can access which endpoints. Realms let you separate public-facing traffic from administrative traffic, or partition access between different user groups, without duplicating your project configuration.

Realms are defined at the project level and are stored in the JWT’s realm claim. The platform validates the realm claim on every request and enforces ACL rules based on it.

Realm Types

Platform Realm

The platform realm covers all interactions with the Oblax platform itself — managing projects, organizations, billing, and user accounts. Platform tokens are issued by platform.oblax.io and carry the realm: "platform" claim.

{
  "iss": "platform.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "realm": "platform",
  "role": "admin"
}

Application Realms

Application realms cover interactions with your user-created applications. The default application realm is app, but you can define custom subrealms to partition access.

{
  "iss": "literate-camel-cnoqeve3lg59f9urb2j0.api.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "realm": "app:webapp",
  "role": "admin"
}

Custom Subrealms

You can create as many subrealms as you need. Common patterns include:

Subrealms are dynamic — you define them when creating sessions and reference them in ACL rules. The platform does not require pre-registration of realm names.

Realms and Sessions

When you create a session using the SDK, you specify a realm as the first argument. This determines which access scope the session operates in.

await oblax.session.create('webapp', {
  email: 'user@example.com',
  password: 'secret123',
});

await oblax.session.create('admin', {
  email: 'admin@example.com',
  password: 'secret123',
});

Each session issues a JWT with a different realm claim. The webapp session carries realm: "app:webapp" and the admin session carries realm: "app:admin".

Realms and ACL

ACL rules reference realms to control endpoint access. A rule might allow only app:admin tokens to access a management endpoint, while app:webapp tokens can access public endpoints.

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

When a request arrives, the platform checks the token’s realm claim against the ACL rule’s allowedRealms list. If the realm is not in the list, the request is rejected.

Where to next