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

# Authentication

> Create and use a Maito API key for server-side API requests.

Maito customer API requests authenticate with an API key.

<Warning>
  API keys are server-side secrets. Do not expose them in browser JavaScript, static websites, public repositories, logs, or mobile app bundles.
</Warning>

## Create An API Key

1. Open Maito and go to **Settings**.
2. Open **API Keys** in the Developer section.

<img src="https://mintcdn.com/maito/wTBWCQL3FzkO-iKk/images/api-authentication/api-keys-settings.jpg?fit=max&auto=format&n=wTBWCQL3FzkO-iKk&q=85&s=8fe320c8a1cf78fb696b1d559a0b535b" alt="Maito API Keys settings page" width="520" data-path="images/api-authentication/api-keys-settings.jpg" />

3. Click **Create**.
4. Give the key a clear name, such as `Production`, `Docs website`, or `Internal tool`.
5. Choose an expiration policy.

<img src="https://mintcdn.com/maito/wTBWCQL3FzkO-iKk/images/api-authentication/create-api-key-named.jpg?fit=max&auto=format&n=wTBWCQL3FzkO-iKk&q=85&s=57ac0ceaa1e50fbe9ce06ee8e9111b49" alt="Create API key dialog in Maito" width="520" data-path="images/api-authentication/create-api-key-named.jpg" />

6. Click **Create key**.
7. Copy the key immediately. Maito shows the secret only once.

<img src="https://mintcdn.com/maito/wTBWCQL3FzkO-iKk/images/api-authentication/copy-api-key-redacted.jpg?fit=max&auto=format&n=wTBWCQL3FzkO-iKk&q=85&s=d8f1421c20babe433cb2e84ff0aec545" alt="Copy API key dialog with the API key redacted" width="520" data-path="images/api-authentication/copy-api-key-redacted.jpg" />

8. Store the key in a secret manager or server-side environment variable.

<img src="https://mintcdn.com/maito/wTBWCQL3FzkO-iKk/images/api-authentication/api-key-created-list.jpg?fit=max&auto=format&n=wTBWCQL3FzkO-iKk&q=85&s=6c5fd0118c3938948711f5db100b0bb6" alt="Created API key listed in Maito settings" width="520" data-path="images/api-authentication/api-key-created-list.jpg" />

API keys are shown only when they are created. If you lose a key, revoke it and create a new one.

## Use The Key

Send the API key as a Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer <token>
```

For example:

```bash theme={null}
curl "https://api.getmaito.com/v1/newsletter/subscribers" \
  -H "Authorization: Bearer $MAITO_API_KEY" \
  -H "Accept: application/json"
```

## Server-Side Usage

Store API keys outside source control:

```bash theme={null}
MAITO_API_KEY="your_api_key"
```

Then read the key from the runtime environment in your integration. Do not expose API keys in browser-side code, public repositories, logs, or client bundles.

## Rotate Or Revoke A Key

If a key is exposed or no longer needed:

1. Open **Settings**.
2. Open **API Keys**.
3. Revoke the old key.
4. Create a replacement key if the integration still needs access.

Update every integration that used the old key.

## Authentication Errors

Requests without a valid API key return an error response.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required."
  }
}
```

Exact messages can vary by route. Clients should treat HTTP `401` as an authentication failure and ask for a new or corrected API key.

API keys can only call supported customer API endpoints. If a valid key calls an app-only or internal route, Maito returns `403`.