# API keys API

> Create, list and delete API keys. Requires a `full` access key.

Source: https://mailvina.com/docs/api-reference/api-keys · Base URL: https://api.mailvina.com · Guide: https://mailvina.com/docs/api-keys

## Create API key

Creates a key. The `token` is returned only in this response, so store it securely.

`POST /api-keys`

**Body parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | A name to recognise the key, e.g. `Production`. |
| `permission` | `'full' \| 'sending_access'` | no | Default `full`. |
| `domain_id` | `string` | no | Limit the key to one sending domain. |

**Request**

```bash
curl -X POST 'https://api.mailvina.com/api-keys' \
  -H 'Authorization: Bearer mv_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Production",
  "permission": "sending_access"
}'
```

```js
const res = await fetch('https://api.mailvina.com/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Production",
    "permission": "sending_access"
  }),
});
const data = await res.json();
```

```python
import os, requests

res = requests.post(
    "https://api.mailvina.com/api-keys",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
    json={
        "name": "Production",
        "permission": "sending_access"
    },
)
print(res.json())
```

**Response**

```json
{
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "token": "mv_123456789_abcdefghijklmnop"
}
```

## List API keys

Lists active keys. Tokens are never returned again.

`GET /api-keys`

**Request**

```bash
curl -X GET 'https://api.mailvina.com/api-keys' \
  -H 'Authorization: Bearer mv_xxxxxxxxx'
```

```js
const res = await fetch('https://api.mailvina.com/api-keys', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.mailvina.com/api-keys",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
)
print(res.json())
```

**Response**

```json
{
  "object": "list",
  "data": [
    {
      "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
      "name": "Production",
      "permission": "sending_access",
      "created_at": "2026-11-14T10:00:00.000Z",
      "last_used_at": "2026-11-14T10:00:00.000Z"
    }
  ]
}
```

## Delete API key

Revokes a key. Requests using it fail immediately.

`DELETE /api-keys/:id`

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | The API key ID. |

**Request**

```bash
curl -X DELETE 'https://api.mailvina.com/api-keys/:id' \
  -H 'Authorization: Bearer mv_xxxxxxxxx'
```

```js
const res = await fetch('https://api.mailvina.com/api-keys/:id', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os, requests

res = requests.delete(
    "https://api.mailvina.com/api-keys/:id",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
)
print(res.json())
```

**Response**

```json
{
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "revoked": true
}
```