Session

A Session object represents an authenticated user session. Sessions are created on login and provide a JWT token for authenticating subsequent API requests. Each session is scoped to a specific realm and carries the user’s identity, role, and project information.

Sample Object

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

Fields

Actions

Creating a session

Authenticate with email and password to receive a JWT token and a refresh token. The realm parameter specifies the authentication portal.

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

POST /api/v1/auth/session/app

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

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

Creating an anonymous session

Create a session without authentication credentials. Anonymous sessions are used for unauthenticated users and carry a special $anonymous role.

const session = await oblax.auth.session.anonymous("app");

GET /api/v1/auth/session/app/anonymous

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "",
  "expiration": 0
}

Destroying a session

Log out by destroying the current session. This invalidates the JWT token and clears the session cookie.

await oblax.auth.session.destroy("app");

DELETE /api/v1/auth/session/app

Refreshing a session

Refresh an expiring JWT token using the refresh token obtained during login.

const session = await oblax.auth.session.refresh("app", "rt_abc123def456");

PUT /api/v1/auth/session/app/rt_abc123def456