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

# Authentication

> Authenticate with the BosonMail API using a Bearer token passed to the SDK constructor. Covers API keys, scopes, environment variables, and security practices.

The BosonMail SDK authenticates every request with a Bearer token sent in the `Authorization` header. You provide the token as `apiKey` when constructing the client. The SDK handles headers automatically; you never set them manually.

## Provide your API key

Pass the key directly to the constructor, typically from an environment variable.

```typescript lib/bosonmail.ts theme={null}
import BosonMailClient from "@bosonware-ent/bosonmail";

const apiKey = process.env.BOSONMAIL_API_KEY;
if (!apiKey) {
  throw new Error("BOSONMAIL_API_KEY is not set");
}

export const bosonmail = new BosonMailClient({ apiKey });
```

The SDK stores the key on the readonly `apiKey` property. Avoid logging the client object because it contains the key.

## Constructor validation

The constructor validates the `apiKey` immediately and throws if it is missing or invalid:

* Empty or whitespace-only string: `Error("'apiKey' must be a non-empty string")`

This is the only place the SDK throws. All method failures return `{ success: false }` objects instead of rejecting.

## API key scopes

Scopes determine the actions a token can perform:

* `email:read`: allows calling `getEmailStatus`.
* `email:send`: allows sending emails via `sendEmail` and also calling `getEmailStatus:`requires either `email:read` or `email:send`.
* `sendEmail`: Requires `email:send`.

## What happens with an invalid key

If the API rejects the key, the SDK returns a typed failure object rather than throwing:

* `sendEmail` returns `{ success: false, statusCode: <HTTP status>, errorMessage: <message> }`
* `getEmailStatus` returns `{ success: false, errorCode: "unauthorized", errorMessage: <message>, statusCode: <HTTP status> }`

## Raw HTTP example

If you are debugging or writing a non-Node client, the header format is:

```bash curl theme={null}
curl -X POST https://webmail.bosonware.com/api/v1/emails/send \
  -H "Authorization: Bearer $BOSONMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"customer@example.com","subject":"Hello","text":"Test"}'
```

## Server-only warning

> [!WARNING]
>
> Never expose your BosonMail API key in browser code, frontend environment variables, or client-side bundles. The key grants access to your email account. Always call the SDK from a server, API route, or serverless function.

Recommended practices:

* Store the key in a secrets manager or encrypted environment variable
* Do not commit `.env` files containing the key
* Do not log the client object or the key itself
* Rotate keys periodically if BosonWare supports it

## Next steps

> [card] [Configuration](https://docs.bosonware.com/configuration.md)
>
> Set base URLs, timeouts, and per-environment client instances.

> [card] [API keys](https://docs.bosonware.com/advanced/api-keys.md)
>
> Key management, rotation, and access control.

> [card] [Security](https://docs.bosonware.com/advanced/security.md)
>
> Secrets handling, credential hygiene, and safe deployment.

> [card] [Quickstart](https://docs.bosonware.com/quickstart.md)
>
> Send your first authenticated email.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.