Authenticate the Figranium SDK

The Figranium SDK supports two authentication modes: an API key sent as an HTTP header, or a browser session cookie. Pick one; they are mutually exclusive.

Choose an authentication mode

Decide whether you want API key authentication (best for automation) or session authentication (required for settings management).

API key authentication

The default and most common mode. Figranium sends the key as Authorization: Bearer <key>.

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

const figranium = new Figranium({
  baseUrl: "http://localhost:11345",
  apiKey: process.env.FIGRANIUM_API_KEY!,
});

Switching headers

Some deployments expect x-api-key instead of the Authorization header. Set apiKeyHeader: "x-api-key":

new Figranium({
  apiKey: process.env.FIGRANIUM_API_KEY!,
  apiKeyHeader: "x-api-key",
});

Only "authorization" (default) and "x-api-key" are valid values.

What API keys can access

API keys authenticate every task, execution, schedule, capture, credential, browser, and execution endpoint. They cannot call settings.* endpoints, which require a user session.

Browser session authentication

Set session: true to authenticate with cookies. The SDK sets credentials: "include" so cookies are attached to every request.

const admin = new Figranium({
  baseUrl: "https://figranium.example",
  session: true,
});

await admin.auth.login({ email: "you@example.com", password: "..." });

Session mode is required for anything under settings (API key management, AI providers, theme, user agent, and proxies).Node’s built-in fetch does not persist cookies between requests. If you need to drive session endpoints from Node, provide a cookie-aware fetch implementation via the fetch option:

import { Figranium } from "@figranium/sdk";
import { fetch as cookieFetch } from "your-cookie-aware-fetch";

const admin = new Figranium({
  baseUrl: "https://figranium.example",
  session: true,
  fetch: cookieFetch,
});

In the browser, cookies are handled natively; no extra setup is needed.

First-time server setup

If Figranium has not been initialized yet, use auth.checkSetup() and auth.setup() to create the first user. This does not require any credentials.

const client = new Figranium({ baseUrl: "https://figranium.example", session: true });

const { setupRequired } = await client.auth.checkSetup();
if (setupRequired) {
  await client.auth.setup({
    name: "Admin",
    email: "admin@example.com",
    password: "a-strong-password",
  });
}

Rotate an API key

Session-authenticated admins can rotate keys through settings.setApiKey:

const { apiKey } = await admin.settings.setApiKey(); // generates a new key

Pass a string to setApiKey to set a specific value instead of generating one.

Store API keys in environment variables or a secrets manager. Never commit keys to source control or expose them in client-side code.

Client configuration

All available client options, including baseUrl and timeoutMs.

Settings resource

Session-only endpoints for API keys, AI providers, theme, and proxies.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

Authenticate the Figranium SDK

Switching headers

What API keys can access

First-time server setup

Rotate an API key

Client configuration

Settings resource

​Switching headers

​What API keys can access

​Node.js and cookie jars

​First-time server setup

​Rotate an API key

​Related

Client configuration

Settings resource

Switching headers

What API keys can access

Node.js and cookie jars

First-time server setup

Rotate an API key

Related