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

# Authentication

> How to authenticate with the MailBreeze API

## API Keys

All API requests require authentication via an API key. You can create and manage keys in your [dashboard](https://console.mailbreeze.com/settings/api-keys).

### Key Types

| Key Prefix | Environment | Description                            |
| ---------- | ----------- | -------------------------------------- |
| `sk_live_` | Production  | Sends real emails, uses credits        |
| `sk_test_` | Sandbox     | Simulates sending, no emails delivered |

### Authenticating Requests

Include your API key in the `x-api-key` header:

```bash theme={null}
curl -X POST https://api.mailbreeze.com/v1/emails \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Or with SDKs:

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { MailBreeze } from "mailbreeze";

  const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });
  ```

  ```python Python theme={null}
  from mailbreeze import MailBreeze

  client = MailBreeze(api_key="sk_live_xxx")
  ```

  ```go Go theme={null}
  import mailbreeze "github.com/MailBreeze/mailbreeze-go"

  client := mailbreeze.NewClient("sk_live_xxx")
  ```

  ```php PHP theme={null}
  use MailBreeze\MailBreeze;

  $mailbreeze = new MailBreeze('sk_live_xxx');
  ```

  ```rust Rust theme={null}
  use mailbreeze::Client;

  let client = Client::new("sk_live_xxx");
  ```
</CodeGroup>

## Key Permissions

API keys have full access to all endpoints for your domain. To restrict access:

* Create separate keys for different applications
* Revoke unused keys immediately
* Rotate keys periodically

## Security Best Practices

<Warning>
  Never expose your API key in client-side code, public repositories, or logs.
</Warning>

### Do

* Store keys in environment variables
* Use secret management systems (e.g., AWS Secrets Manager, Vault)
* Rotate keys after team member departures
* Use test keys for development

### Don't

* Commit keys to version control
* Share keys via email or chat
* Use production keys in CI/CD logs
* Hardcode keys in source code

## Environment Variables

Store your API key in an environment variable:

<CodeGroup>
  ```bash .env theme={null}
  MAILBREEZE_API_KEY=sk_live_xxx
  ```

  ```typescript JavaScript theme={null}
  const mailbreeze = new MailBreeze({
    apiKey: process.env.MAILBREEZE_API_KEY,
  });
  ```

  ```python Python theme={null}
  import os
  from mailbreeze import MailBreeze

  client = MailBreeze(api_key=os.environ["MAILBREEZE_API_KEY"])
  ```

  ```go Go theme={null}
  client := mailbreeze.NewClient(os.Getenv("MAILBREEZE_API_KEY"))
  ```
</CodeGroup>

## Error Responses

Authentication errors return a `401 Unauthorized` status:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

| Error Code     | Description                |
| -------------- | -------------------------- |
| `UNAUTHORIZED` | Missing or invalid API key |
| `KEY_REVOKED`  | API key has been revoked   |
| `KEY_EXPIRED`  | API key has expired        |

## Rate Limits

API requests are rate limited to **100 requests per minute** per API key.

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2024-01-01T12:01:00Z
```

| Header                  | Description                          |
| ----------------------- | ------------------------------------ |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute  |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset`     | ISO timestamp when the limit resets  |

When exceeded, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating seconds until reset.