warmbly/docs/content/docs/api-keys/create.mdx

---
title: Create API Key
description: Create a new API key with specific permissions.
---

# Create API Key

Create a new API key for programmatic access to the Warmbly API.

```
POST /api-keys
```

## Request

### Headers

| Header | Value |
|--------|-------|
| `Authorization` | `Bearer wmbly_<your_key>` |
| `Content-Type` | `application/json` |

### Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable name (max 255 chars) |
| `permissions` | integer | Yes | Bitmask of permissions to grant |
| `allowed_ips` | array | No | List of allowed IP addresses |
| `allowed_email_accounts` | array | No | List of allowed email account UUIDs |
| `expires_at` | timestamp | No | When the key should expire |

### Example Request

```bash
curl -X POST "https://api.warmbly.com/api-keys" \
  -H "Authorization: Bearer wmbly_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "permissions": 31,
    "allowed_ips": ["203.0.113.10"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'
```

## Response

### Success Response (201 Created)

<Callout type="warn" title="Save Your Secret">
  The `secret` field is only returned once during creation. Store it securely - you cannot retrieve it later.
</Callout>

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "organization_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
  "name": "Production Integration",
  "key_prefix": "wmbly_abc",
  "permissions": 31,
  "allowed_ips": ["203.0.113.10"],
  "allowed_email_accounts": [],
  "status": "active",
  "last_used_at": null,
  "expires_at": "2025-12-31T23:59:59Z",
  "revoked_at": null,
  "revoked_reason": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "secret": "wmbly_abc123def456ghi789..."
}
```

### Error Responses

#### 400 Bad Request

Invalid request body:

```json
{
  "error": "Bad Request",
  "message": "invalid request body"
}
```

#### 401 Unauthorized

Missing or invalid API key:

```json
{
  "error": "Unauthorized",
  "message": "Token not found."
}
```

#### 403 Forbidden

API key lacks `API_KEYS` permission:

```json
{
  "error": "Forbidden",
  "message": "You doesn't have access to this feature."
}
```

## Permission Combinations

Here are some common permission combinations:

### Read-Only Access

```json
{
  "name": "Read-Only Key",
  "permissions": 31
}
```

Includes: `READ_EMAILS`, `READ_CAMPAIGNS`, `READ_CONTACTS`, `READ_UNIBOX`, `READ_ANALYTICS`

### Standard Write Access

```json
{
  "name": "Standard Key",
  "permissions": 479
}
```

Includes all read permissions plus: `WRITE_EMAILS`, `WRITE_CAMPAIGNS`, `WRITE_CONTACTS`, `WRITE_UNIBOX`

### Full Access

```json
{
  "name": "Full Access Key",
  "permissions": 16383
}
```

Includes all available permissions. Use with caution.

## Code Examples

### Using JavaScript/Node.js

```javascript
const response = await fetch('https://api.warmbly.com/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Integration',
    permissions: 31,
  }),
});

const data = await response.json();
console.log('New API Key:', data.secret);
// Store this secret securely!
```

### Using Python

```python
import requests

response = requests.post(
    'https://api.warmbly.com/api-keys',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'My Integration',
        'permissions': 31,
    }
)

data = response.json()
print('New API Key:', data['secret'])
# Store this secret securely!
```

## See Also

- [List API Keys](/api-keys/list)
- [Permissions Reference](/reference/permissions)
- [Authentication Guide](/authentication)