> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the Figranium SDK

> Authenticate the Figranium JavaScript SDK with an API key or a browser session. Header formats, session-only endpoints, and Node cookie handling.

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.

<Steps>
  <Step title="Choose an authentication mode">
    Decide whether you want API key authentication (best for automation) or session authentication (required for settings management).
  </Step>

  <Step title="API key authentication">
    The default and most common mode. Figranium sends the key as `Authorization: Bearer <key>`.

    ```ts theme={null}
    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"`:

    ```ts theme={null}
    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.
  </Step>

  <Step title="Browser session authentication">
    Set `session: true` to authenticate with cookies. The SDK sets `credentials: "include"` so cookies are attached to every request.

    ```ts theme={null}
    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`](/docs/sdk/js/resources/settings) (API key management, AI providers, theme, user agent, and proxies).

    ### Node.js and cookie jars

    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:

    ```ts theme={null}
    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.
  </Step>
</Steps>

## 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.

```ts theme={null}
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`](/docs/sdk/js/resources/settings):

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

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

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

## Related

<CardGroup cols={2}>
  <Card title="Client configuration" icon="sliders" href="/docs/sdk/js/client-configuration">
    All available client options, including `baseUrl` and `timeoutMs`.
  </Card>

  <Card title="Settings resource" icon="gear" href="/docs/sdk/js/resources/settings">
    Session-only endpoints for API keys, AI providers, theme, and proxies.
  </Card>
</CardGroup>