AuthResource: Session Setup and User Management

The AuthResource on figranium.auth handles server setup, session authentication, and user identity. Use it to initialize a fresh Figranium server, authenticate with email and password, and retrieve the currently logged in user. Session-based methods require new Figranium({ session: true }). For API key authentication details, see Authentication.

import { Figranium } from "@figranium/sdk";

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });

Methods

checkSetup

figranium.auth.checkSetup(options?: RequestOptions): Promise<{ setupRequired: boolean }>

Checks whether the Figranium server has been initialized with a first-time admin account. This endpoint does not require authentication.

HTTP endpoint: GET /api/auth/check-setup

check-setup.ts

const { setupRequired } = await figranium.auth.checkSetup();

if (setupRequired) {
  console.log("Server needs first-time setup");
}

setup

figranium.auth.setup(
  input: { name: string; email: string; password: string },
  options?: RequestOptions
): Promise<{ success: boolean }>

Creates the first admin account on a fresh Figranium server. Call this only when checkSetup returns { setupRequired: true }. No credentials are required for this call.

HTTP endpoint: POST /api/auth/setup

first-setup.ts

const result = await figranium.auth.setup({
  name: "Admin User",
  email: "admin@example.com",
  password: "secure-password-123",
});

console.log(result.success);

figranium.auth.login(
  input: { email: string; password: string },
  options?: RequestOptions
): Promise<{ success: boolean }>

Authenticates with email and password and establishes a session cookie. This method requires a session-enabled client (new Figranium({ session: true })). In Node.js, supply a cookie-aware fetch implementation because the default fetch does not preserve cookies.

HTTP endpoint: POST /api/auth/login

session-login.ts

import { Figranium } from "@figranium/sdk";

const sessionClient = new Figranium({
  baseUrl: "http://localhost:11345",
  session: true,
});

const result = await sessionClient.auth.login({
  email: "admin@example.com",
  password: "secure-password-123",
});

console.log(result.success);

Session-only endpoints like login, logout, and me require session: true. API key clients should not call these methods.

logout

figranium.auth.logout(options?: RequestOptions): Promise<{ success: boolean }>

Ends the current session and invalidates the session cookie. Requires a session-enabled client.

HTTP endpoint: POST /api/auth/logout

logout.ts

const result = await sessionClient.auth.logout();
console.log(result.success);

figranium.auth.me(options?: RequestOptions): Promise<{ user: User }>

Returns the currently authenticated user. Requires a session-enabled client. The User type is { id?: string; name: string; email: string }.

HTTP endpoint: GET /api/auth/me

me.ts

const { user } = await sessionClient.auth.me();

console.log(user.name);
console.log(user.email);

Return types

checkSetup returns { setupRequired: boolean }
setup returns { success: boolean }
login returns { success: boolean }
logout returns { success: boolean }
me returns { user: User } where User = { id?: string; name: string; email: string }

Error handling

All methods throw FigraniumError on failure. Common cases include invalid credentials on login, missing session on me, and calling setup on an already-initialized server. See Errors for details on status codes, error codes, and retry behavior.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

AuthResource: Session Setup and User Management

Methods

Return types

Error handling

​Methods

​Return types

​Error handling

Methods

Return types

Error handling