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

# Authentication

> How to authenticate requests for the dashboard and the public MsgFlash API.

## The two surfaces

| Surface    | Method     | Header                        | Usage                                                   |
| ---------- | ---------- | ----------------------------- | ------------------------------------------------------- |
| Dashboard  | JWT Bearer | `Authorization: Bearer <jwt>` | Web interface and console `/api/*` endpoints            |
| Public API | API key    | `x-api-key: <api_key>`        | `/api/v1/*` endpoints for server-to-server integrations |

For any server-to-server integration, use an API key.

<Note>
  The web console and the public API do not use the same authentication method.
</Note>

***

## API key format

A MsgFlash API key looks like this:

```txt theme={null}
msgf_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
```

Structure:

* prefix `msgf_live_`
* 64 lowercase hexadecimal characters

<Note>
  The full key is only shown once when it is created.
</Note>

***

## Using your API key

```bash theme={null}
curl https://srv.msgflash.com/api/v1/messages/send \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "to": "+33612345000",
    "type": "text",
    "text": "Hello"
  }'
```

<Warning>
  Do not use `Authorization: Bearer <api_key>` for the public API. The backend explicitly expects the `x-api-key` header.
</Warning>

***

## Creating and revoking a key

1. Sign in to [app.msgflash.com](https://app.msgflash.com)
2. Open **API Keys**
3. Click **New API Key**
4. Give it a descriptive name
5. Copy the key immediately

To revoke a key:

1. Go back to **API Keys**
2. Click **Revoke**
3. Confirm

Revocation is immediate.

***

## Dashboard authentication

The main dashboard flows are:

* signup
* login
* Google OAuth
* email verification
* password reset

Detailed guide:

[See the dashboard auth guide](/guides/dashboard-auth)

***

## Number of keys per plan

| Plan    | Allowed API keys |
| ------- | ---------------- |
| Free    | 1                |
| Starter | 3                |
| Pro     | 10               |
| Plus    | 10               |

***

## Best practices

<CardGroup cols={2}>
  <Card title="One key per environment" icon="key">
    Use separate keys for production, staging, and development.
  </Card>

  <Card title="Environment variables" icon="lock">
    Store your key in an environment variable such as `MSGFLASH_API_KEY` or in a secrets manager.
  </Card>
</CardGroup>

***

## Authentication-related errors

| Code                                 | HTTP | Description                                                               |
| ------------------------------------ | ---- | ------------------------------------------------------------------------- |
| `UNAUTHORIZED`                       | 401  | Missing, invalid, or revoked key                                          |
| `FORBIDDEN`                          | 403  | The key is valid but cannot access the resource                           |
| `SUBSCRIPTION_INACTIVE`              | 403  | The account no longer has an active subscription for the requested action |
| `API_RATE_LIMIT_EXCEEDED`            | 429  | More than 10 requests/second on the same key                              |
| `MONTHLY_API_REQUEST_QUOTA_EXCEEDED` | 429  | Monthly API request quota exhausted                                       |

Example:

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