Authentication and Authorization

Overview

Oblax uses JSON Web Tokens (JWTs) for authentication and authorization. Every API request carries a JWT that identifies the caller, their project, their realm, and their role. The platform validates these tokens on every request and uses the claims inside them to enforce access control.

There are two distinct token types: platform JWTs for managing the Oblax platform itself, and application JWTs for interacting with your user-created applications. Both follow the same structure but operate in different realms with different claim sets.

Token Types

Platform JWTs

Used when interacting with the Oblax platform — managing projects, organizations, billing, and user accounts.

{
  "iss": "platform.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "aud": "platform.oblax.io",
  "exp": 2524608000,
  "iat": 1596240000,
  "nbf": 0,
  "full_name": "Your Name",
  "pid": "cnoqeve3lg56dnbek55g",
  "realm": "platform",
  "role": "admin"
}

Application JWTs

Used when interacting with your application’s API — submitting forms, managing bookmarks, executing flux scripts.

{
  "iss": "literate-camel-cnoqeve3lg59f9urb2j0.api.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "aud": "literate-camel-cnoqeve3lg59f9urb2j0.api.oblax.io",
  "exp": 2524608000,
  "iat": 1596240000,
  "nbf": 0,
  "full_name": "Your Name",
  "email": "you@example.com",
  "pid": "cnoqeve3lg56dnbek55g",
  "realm": "app:webapp",
  "role": "admin"
}

JWT Claims

Subject Formats

The sub claim uses a prefix to distinguish between human users and external services:

Service tokens are used when an external system integrates with your Oblax project — for example, a webhook consumer or a cron job that needs to interact with your API.

Session Management

The SDK provides a session module that handles authentication automatically. When you create a session, the SDK stores the JWT, sends it with every request, and refreshes it before expiry.

const oblax = new Oblax({
  clientAppId: 'literate-camel-cnoqeve3lg59f9urb2j0',
  platform: browserPlatform(),
  modules: [session(), bookmarks()],
});

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

const mine = await oblax.bookmarks.listMine('article');

The session.create call takes a realm as its first argument. This determines which access scope the token operates in. You can create multiple sessions with different realms — for example, a webapp realm for end users and an admin realm for application administrators.

Anonymous Sessions

For public-facing applications that do not require user identification, Oblax supports anonymous sessions. An anonymous session issues a JWT without credentials, granting limited access to public resources.

await oblax.session.anonymous('webapp');
const publicData = await oblax.bookmarks.listMine('article');

Token Refresh

The SDK handles token refresh transparently. When a JWT approaches expiry, the SDK uses the refresh token to obtain a new JWT without interrupting your application logic.

const oblax = new Oblax({
  clientAppId: 'literate-camel-cnoqeve3lg59f9urb2j0',
  platform: browserPlatform(),
  modules: [session({ refreshSkewMs: 10_000 }), bookmarks()],
});

You can also manage tokens manually by disabling auto-refresh and calling setToken() yourself.

Where to next