Authentication and API keys

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.

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

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.

lib/bosonmail.ts

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.

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:

Create a new key

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

Update your services

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

Verify traffic

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

Revoke the old key

Remove the old key from the dashboard or request revocation via support@bosonware.com.

The exact BosonWare dashboard steps for creating and revoking keys require confirmation. Contact support@bosonware.com for assistance.

If a key is leaked

Revoke the leaked key immediately via the dashboard or by emailing support@bosonware.com.
Rotate to a new key using the procedure above.
Audit recent send logs and status checks for unexpected activity.
Review access controls to prevent recurrence.

Next steps

Security best practices

Server-side-only usage, PII handling, and dependency hygiene.

Client configuration

Configure API base URL, timeouts, and other options.

Error codes

Understand unauthorized and not_found errors.

Troubleshooting

Fix common authentication and configuration problems.

Getting Started

SDK Reference

Guides

Advanced

Resources

Authentication and API keys

Known scopes

Storing API keys

Environment variables

Platform secrets

Key rotation

If a key is leaked

Next steps

Security best practices

Client configuration

Error codes

Troubleshooting

​Known scopes

​Storing API keys

​Environment variables

​Platform secrets

​Key rotation

​If a key is leaked

​Next steps

Security best practices

Client configuration

Error codes

Troubleshooting

Known scopes

Storing API keys

Environment variables

Platform secrets

Key rotation

If a key is leaked

Next steps