API key authentication for every request

Create a key in the dashboard, pass it as a Bearer token, and start sending.

Last updated April 2026

API Key Format

All BaviMail API keys use the bav_live_ prefix followed by a random string:

bav_live_a1b2c3d4e5f6g7h8i9j0...

The prefix lets you identify BaviMail keys in your codebase and secrets scanners.

Authenticating Requests

Pass your API key as a Bearer token in the Authorization header:

curl -X POST https://api.bavimail.com/v2/emails \
  -H "Authorization: Bearer bav_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"aliasId": "alias_abc123", "toEmail": "user@example.com", "subject": "Hello", "body": "<p>Hi</p>"}'

SDK Initialization

import { BaviMail } from 'bavimail'

// Reads BAVIMAIL_API_KEY from env by default
const client = new BaviMail()

// Or pass explicitly
const client = new BaviMail({ apiKey: 'bav_live_your_key_here' })

Key Management

Create a Key

Open the dashboard

Go to Settings > API Keys in the dashboard.

Create the key

Click Create API Key.

Name the key

Name it something descriptive (e.g., production-backend, staging-agent).

Copy immediately

Copy the key immediately -- it is shown only once.

Revoke a Key

Find the key

Go to Settings > API Keys.

Revoke it

Find the key and click Revoke.

Immediate effect

The key stops working immediately. Any request using it returns 401.

Rotate a Key

Create a new key

Create a new key from the dashboard.

Deploy the new key

Deploy the new key to your application.

Verify traffic

Verify traffic is flowing on the new key.

Revoke the old key

Revoke the old key.

There is no downtime if you run both keys in parallel during rotation.

Security Best Practices

Never commit keys to version control. Use environment variables or a secrets manager.
Use separate keys per environment. One for production, one for staging, one for development.
Set the narrowest permissions needed. If a key only needs to send email, don't grant domain management.
Rotate keys periodically. At minimum, rotate when a team member leaves or a key may have been exposed.
Monitor key usage. Check the dashboard for unexpected spikes in API calls.

Error Responses

Status	Code	Description
`401`	`unauthorized`	Missing or invalid API key. Check that your `Authorization` header is `Bearer bav_live_...`.
`403`	`forbidden`	The API key is valid but lacks permission for this action. Check key permissions in the dashboard.

Quickstart

API Overview