> ## 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 and API keys

> How to manage BosonMail API keys securely: scopes, storage, rotation, and incident response for leaked credentials.

BosonMail authenticates API requests with Bearer tokens passed in the `Authorization` header. This page covers what is known about key scopes, how to store keys safely, and how to rotate them without downtime.

> [!WARNING]
>
> BosonWare has not published the exact steps for creating, revoking, or scoping API keys in the dashboard. The guidance below is based on general security practices. Contact [support@bosonware.com](mailto:support@bosonware.com) to confirm BosonWare's specific key management UI and capabilities.

## Known scopes

The BosonMail README mentions two permission scopes:

| Scope | Likely purpose |
| - | - |
| `email:send` | Submit emails via `sendEmail`. Whether this is strictly required for sending is not confirmed by BosonWare. |
| `email:read` | Retrieve email status via `getEmailStatus`. Also accepted for status lookups according to the README. |

Apply the principle of least privilege: use a key with only the scopes needed for a given service. For example, a status dashboard might only need `email:read`, while a transactional backend needs `email:send`.

> [!NOTE]
>
> The full list of available scopes, and whether BosonWare supports scoped keys, requires confirmation from BosonWare.

## Storing API keys

Never hardcode keys in source code or commit them to version control. Use one of the following approaches.

### Environment variables

Load the key from the environment at runtime and validate it before constructing the client.

```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 });
```

### Platform secrets

| Platform | How to store |
| - | - |
| Vercel | Add `BOSONMAIL_API_KEY` in Project Settings > Environment Variables. |
| Cloudflare Workers | Use `wrangler secret put BOSONMAIL_API_KEY` and read from `c.env.BOSONMAIL_API_KEY` in your handler. |
| Docker | Pass the key at runtime with `-e BOSONMAIL_API_KEY=...` or use Docker secrets in Swarm mode. |
| AWS / GCP / Azure | Store in Secrets Manager, Parameter Store, or Key Vault and inject into the runtime. |

> [!WARNING]
>
> Do not prefix the variable with `NEXT_PUBLIC_`, `VITE_`, or any framework-specific public prefix. That would bundle the key into client-side JavaScript.

## Key rotation

Rotate keys periodically and immediately after any suspected leak. The general procedure is:

**1. Create a new key**

Generate a new API key in the BosonWare dashboard or by contacting support. Do not delete the old key yet.

**2. Update your services**

Deploy the new key to all environments that use BosonMail. Keep the old key active during the transition.

**3. Verify traffic**

Confirm that emails are sending and status lookups are working with the new key.

**4. Revoke the old key**

Remove the old key from the dashboard or request revocation via [support@bosonware.com](mailto:support@bosonware.com).

> [!NOTE]
>
> The exact BosonWare dashboard steps for creating and revoking keys require confirmation. Contact [support@bosonware.com](mailto:support@bosonware.com) for assistance.

## If a key is leaked

1. Revoke the leaked key immediately via the dashboard or by emailing [support@bosonware.com](mailto:support@bosonware.com).
2. Rotate to a new key using the procedure above.
3. Audit recent send logs and status checks for unexpected activity.
4. Review access controls to prevent recurrence.

## Next steps

> [card] [Security best practices](https://docs.bosonware.com/advanced/security.md)
>
> Server-side-only usage, PII handling, and dependency hygiene.

> [card] [Client configuration](https://docs.bosonware.com/sdk/client-configuration.md)
>
> Configure API base URL, timeouts, and other options.

> [card] [Error codes](https://docs.bosonware.com/advanced/error-codes.md)
>
> Understand unauthorized and not\_found errors.

> [card] [Troubleshooting](https://docs.bosonware.com/advanced/troubleshooting.md)
>
> Fix common authentication and configuration problems.


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