Skip to main content
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. 
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. 
import { BlueBubblesClient } from 'bluebubbles-sdk';

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

​
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. 
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: 
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. 
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.
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.