Auth – Oblax

Auth

Overview

The Auth module handles all authentication and authorization within an Oblax application. It provides a complete identity and access management stack with support for email and password login, OAuth providers, session management, role-based access control, and audit logging. Resources are organized into accounts (user credentials and identity), sessions (login tokens), realms (authentication portals), roles (permission definitions), and ACL rules (endpoint-level access control). The module also logs every authentication event for audit compliance.

Before You Start

Install the Oblax CLI (obx) and authenticate with obx login.
For SDK usage, install the oblax npm package.
For REST API access, obtain a valid JWT and a project app-id.
Every request requires the Authorization: Bearer <token> header and the X-App-Id header. See the Authentication reference for details.

When to Use

Register new user accounts in your application during sign-up flows.
Authenticate users with email and password or through third-party OAuth providers.
Manage user sessions including login, logout, token refresh, and anonymous sessions.
Define authentication realms to separate customer, admin, and partner login portals.
Create role definitions (admin, manager, user) and control which users can access which resources.
Configure fine-grained ACL rules to restrict access to specific API endpoints by role and realm.
Audit authentication events for security monitoring and compliance.

How It Fits

    flowchart LR
    Client[Client App] --> Auth[Auth]
    Auth --> Account[Account]
    Auth --> Session[Session]
    Auth --> Realm[Realm]
    Auth --> Role[Role]
    Auth --> AuthLog[Auth Log]
    Account --> Identity[Identity]
    Session --> Identity
    Realm --> Role
    ACL[ACL Rules] --> Auth

Works Well With

Identity – Accounts link to Person records for profile and contact information. Sessions carry person identity into downstream requests.
Forms – Authenticated sessions enable form submissions and entry management.
File Manager – Session tokens authorize file uploads and downloads.
Flux Events – Auth events trigger Flux scripts for post-registration workflows, notifications, and custom logic.
Bookmarks – User sessions identify bookmark owners.

Quick Example

Create an account, confirm it, and authenticate with a session.

Initialize an account template file:

obx app auth:accounts init

Edit the generated init.json with account details, then create the account:

obx app auth:accounts create

Confirm the account using the confirmation token:

obx app auth:accounts confirm ab9311310a24a6ddde3c58e61a1bc8aaab3afd6f220ed531d958f41ca315c3e0

List all accounts:

obx app auth:accounts list

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { auth } from "@oblax/auth";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [auth()],
});

Create an account:

const account = await oblax.auth.account.create({
  first_name: "Jane",
  last_name: "Doe",
  email: "jane@example.com",
  password: "securepassword123",
});

Confirm the account:

await oblax.auth.account.confirm({
  confirmation_token: account.confirmation_token,
});

Create a session:

const session = await oblax.auth.session.create("app", {
  email: "jane@example.com",
  password: "securepassword123",
});

Create an account:

POST /api/v1/auth/accounts

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "password": "securepassword123"
}

Successful Response

{
  "id": "acc_abc123def456",
  "owner_id": "ppl_abc123def456",
  "provider": "OBLAX",
  "email": "jane@example.com",
  "confirmed": false,
  "active": false,
  "confirmation_token": "ab9311310a24a6ddde3c58e61a1bc8aaab3afd6f220ed531d958f41ca315c3e0"
}

Confirm the account:

POST /api/v1/auth/accounts/confirmation

{
  "confirmation_token": "ab9311310a24a6ddde3c58e61a1bc8aaab3afd6f220ed531d958f41ca315c3e0"
}

Successful Response

No response body. Status 204 No Content.

Create a session:

POST /api/v1/auth/session/app

{
  "email": "jane@example.com",
  "password": "securepassword123"
}

Successful Response

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_abc123def456",
  "expiration": 1777390896
}

Errors

HTTP Status	Error Code	Description
400	`validation_failed`	Request body validation failed
401	`auth_wrong_credentials`	Email or password is incorrect
401	`auth_account_not_confirmed`	Account has not been confirmed
401	`auth_account_not_active`	Account has been disabled
404	`not_found`	Resource not found
409	`conflict_duplicate_record`	Resource already exists with the given name
409	`conflict_archived_record`	Resource is archived and must be unarchived first
422	`auth_account_already_exist`	An account with this email already exists
422	`auth_unable_to_compare_password`	Password comparison failed
422	`auth_unable_to_create_password_reset_token`	Could not generate a password reset token
422	`auth_portal_not_found`	Authentication realm does not exist
500	`unable_to_insert`	Failed to create the resource

Best Practices

Use the POST /api/v1/auth/accounts endpoint for self-registration and the admin-facing POST /api/v1/auth/accounts with proper authorization for account creation by administrators.
Always confirm accounts before allowing login. Use the confirmation token returned in the create response.
Use anonymous sessions for unauthenticated users browsing public content.
Refresh tokens before they expire. Store the refresh token securely on the client.
Define roles and realms before creating accounts so new users can be assigned immediately.
Enable and disable accounts instead of deleting them. Disabled accounts cannot log in but retain their data.
Format enum values (provider, role type) in uppercase strings.

Related Modules

Identity, Forms, File Manager, Flux Events, Bookmarks