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

# Authentication: Connecting to BlueBubbles Server

> Learn how BlueBubbles Server password-based authentication works, how to pass credentials to the SDK, and how to handle authentication failures.

BlueBubbles Server uses a simple password-based authentication model. Every API request must include the server password as a query parameter, and the SDK handles this for you automatically — you configure credentials once when constructing `BlueBubblesClient` and every subsequent request carries them without any extra work on your part.

## How authentication works

When you create a `BlueBubblesClient`, you pass an `OpenAPIConfig` object that includes your credentials. The underlying HTTP layer reads those credentials before each request and appends them to the outgoing URL as query parameters. You never need to set an `Authorization` header or manually attach a password to individual method calls.

## Configuring password authentication

Pass your server password using the `PASSWORD` field in the config object. Set `BASE` to your server's full base URL.

```typescript theme={null}
import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({
  BASE: 'https://your-server-address',
  PASSWORD: 'your-server-password',
});
```

The `PASSWORD` field accepts either a static string or an async resolver function. The resolver form is useful when you need to fetch the password from a secrets manager or environment variable at request time rather than at startup.

```typescript theme={null}
import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({
  BASE: 'https://your-server-address',
  PASSWORD: async () => process.env.BLUEBUBBLES_PASSWORD ?? '',
});
```

<Tip>
  Store your server password in an environment variable rather than hardcoding it. Use a `.env` file locally and inject it through your deployment platform in production.
</Tip>

## Token-based authentication

The `OpenAPIConfig` type also exposes a `TOKEN` field as an alternative credential mechanism. When `TOKEN` is set, it is sent as a Bearer token in the `Authorization` header rather than as a query parameter.

```typescript theme={null}
import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({
  BASE: 'https://your-server-address',
  TOKEN: 'your-api-token',
});
```

Like `PASSWORD`, `TOKEN` accepts a static string or an async resolver function. Check your BlueBubbles Server documentation to confirm which credential type your server version supports.

## Full config reference

The `OpenAPIConfig` type accepted by `BlueBubblesClient` has the following shape:

```typescript theme={null}
type OpenAPIConfig = {
  BASE: string;                                          // Server base URL (default: 'http://localhost')
  VERSION: string;                                       // API version (default: '1.0.0')
  WITH_CREDENTIALS: boolean;                             // Send cookies with requests (default: false)
  CREDENTIALS: 'include' | 'omit' | 'same-origin';      // Fetch credentials mode (default: 'include')
  TOKEN?: string | ((options: ApiRequestOptions) => Promise<string>);
  USERNAME?: string | ((options: ApiRequestOptions) => Promise<string>);
  PASSWORD?: string | ((options: ApiRequestOptions) => Promise<string>);
  HEADERS?: Record<string, string> | ((options: ApiRequestOptions) => Promise<Record<string, string>>);
  ENCODE_PATH?: (path: string) => string;
};
```

All fields except `BASE`, `VERSION`, `WITH_CREDENTIALS`, and `CREDENTIALS` are optional. At minimum, set `BASE` and `PASSWORD` to connect to a standard BlueBubbles Server instance.

## Handling authentication failures

When a request fails — for example because the password is wrong or the server is unreachable — the SDK throws an `ApiError`. Import it from `bluebubbles-sdk` to check for it specifically.

```typescript theme={null}
import { BlueBubblesClient, ApiError } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({
  BASE: 'https://your-server-address',
  PASSWORD: 'your-server-password',
});

try {
  const response = await client.chats.list({});
  console.log(response.data);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`Request failed: ${error.status} ${error.statusText}`);
    console.error(error.body);
  } else {
    throw error;
  }
}
```

`ApiError` exposes the HTTP `status` code, `statusText`, the request `url`, and the parsed `body` from the server response. A `401` or `403` status typically indicates an incorrect password. A connection error (network failure before the server responds) surfaces as a standard `Error` rather than an `ApiError`.

<Warning>
  If your BlueBubbles Server is behind a firewall or VPN, make sure the machine running your SDK code has network access to the server address you pass as `BASE`. Authentication errors and network errors produce different failure modes — check the error type to distinguish them.
</Warning>