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

# AuthResource: Session Setup and User Management

> Authenticate and manage sessions with the Figranium JavaScript SDK. Check setup status, create the first admin account, log in, log out, and fetch the current user.

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](/docs/sdk/js/authentication).

```ts theme={null}
import { Figranium } from "@figranium/sdk";

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

## Methods

<AccordionGroup>
  <Accordion title="checkSetup">
    ```ts theme={null}
    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`

    ```ts check-setup.ts theme={null}
    const { setupRequired } = await figranium.auth.checkSetup();

    if (setupRequired) {
      console.log("Server needs first-time setup");
    }
    ```
  </Accordion>

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

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

    console.log(result.success);
    ```
  </Accordion>

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

    ```ts session-login.ts theme={null}
    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);
    ```

    <Note>
      Session-only endpoints like `login`, `logout`, and `me` require `session: true`. API key clients should not call these methods.
    </Note>
  </Accordion>

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

    ```ts logout.ts theme={null}
    const result = await sessionClient.auth.logout();
    console.log(result.success);
    ```
  </Accordion>

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

    ```ts me.ts theme={null}
    const { user } = await sessionClient.auth.me();

    console.log(user.name);
    console.log(user.email);
    ```
  </Accordion>
</AccordionGroup>

## 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](/docs/sdk/js/errors) for details on status codes, error codes, and retry behavior.