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

# Consumer Keys API

> Create, list, update, and revoke Consumer Key and Consumer Secret pairs, permissions, and IP restrictions.

Use a Consumer Key and Consumer Secret for production integrations. HTTP requests send them as `consumerKey` and `consumerSecret` headers. SMTP uses the Consumer Key as the username and the Consumer Secret as the password.

You can manage keys in **Settings → Integrations → API Keys → Edit**.

## Authentication

**Base URL:** `https://pro.api.serversmtp.com/api/v2`

Consumer-key management is a session-only exception. Create, list, update, and delete requests require a session API key as the raw `Authorization` value, without `Bearer`:

```http theme={"system"}
Authorization: YOUR_SESSION_API_KEY
```

Consumer credentials return `not_allowed_for_consumerkey` on these routes. Use the dashboard to manage keys if you do not have a working session token. To get a session token, sign in with `POST /authorize` using your dashboard email and password; see [authentication](/docs/api-reference/authentication.md).

## Permissions

| API value | Dashboard service | Access |
| - | - | - |
| `SEND_SMTP` | SMTP Sending | SMTP relay |
| `SEND_API` | HTTP API Sending | `POST /mail/send` |
| `APIS` | Statistics & Management APIs | Analytics and management APIs, subject to session-only exceptions |

If you omit `permissions` when creating a key, all three permissions are granted. Send an explicit nonempty list to limit access.

`ips` is an array of allowed IP addresses. Omitting it on creation or sending `[]` leaves the key unrestricted. Replace example IPs with your application's public outbound IP.

## Create a key

`POST /user/consumerKeys` accepts `label`, `permissions`, and `ips`.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/user/consumerKeys' \
  -H 'Authorization: YOUR_SESSION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Production mailer",
    "permissions": ["SEND_API"],
    "ips": ["203.0.113.10"]
  }'
```

The `201` response contains only the new pair:

```json theme={"system"}
{
  "consumerKey": "YOUR_NEW_CONSUMER_KEY",
  "consumerSecret": "YOUR_NEW_CONSUMER_SECRET"
}
```

> [!WARNING]
>
> Store the secret securely when you create the key. List responses do not include it. Keep both credentials out of client-side code, logs, and version control.

## List keys

```bash Terminal theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/user/consumerKeys' \
  -H 'Authorization: YOUR_SESSION_API_KEY'
```

`GET /user/consumerKeys` returns an object with `count` and `results`:

```json theme={"system"}
{
  "count": 1,
  "results": [
    {
      "consumerKey": "YOUR_CONSUMER_KEY",
      "label": "Production mailer",
      "ips": ["203.0.113.10"],
      "permissions": ["SEND_API"],
      "creation_time": "2026-10-20 10:30:00",
      "is_legacy": false
    }
  ]
}
```

A legacy auto-generated key can have the account email as its `consumerKey` and `is_legacy: true`. The API can list this key even when the dashboard hides it. It remains a Consumer Key for SMTP authentication; new sub-accounts do not receive one automatically.

## Update a key

Use `PUT /user/consumerKeys/{consumerKey}` to update the label, IP restrictions, and permissions. The path contains the Consumer Key string returned by create or list.

Send `permissions` and `ips` on every update. An omitted `permissions` field resets the key to all three permissions, and an omitted `ips` field clears its IP restrictions. Only an omitted `label` stays unchanged. A failed update returns `400` with `Could not update API key`.

```bash Terminal theme={"system"}
curl -X PUT 'https://pro.api.serversmtp.com/api/v2/user/consumerKeys/YOUR_CONSUMER_KEY' \
  -H 'Authorization: YOUR_SESSION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Production mailer",
    "permissions": ["SEND_SMTP", "SEND_API"],
    "ips": ["203.0.113.10"]
  }'
```

## Revoke a key

`DELETE /user/consumerKeys/{consumerKey}` revokes the pair. Update applications that use it before revocation.

```bash Terminal theme={"system"}
curl -X DELETE 'https://pro.api.serversmtp.com/api/v2/user/consumerKeys/YOUR_CONSUMER_KEY' \
  -H 'Authorization: YOUR_SESSION_API_KEY'
```

A successful deletion returns `{"message":"success"}`. An unknown key returns `404` with `message: "key_not_found"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.