mirror of
https://github.com/warmbly/warmbly.git
synced 2026-10-29 00:02:56 +00:00
171 lines
4.2 KiB
Plaintext
171 lines
4.2 KiB
Plaintext
---
|
|
title: Authentication
|
|
description: Learn how to authenticate with the Warmbly API using API keys.
|
|
---
|
|
|
|
# Authentication
|
|
|
|
The Warmbly API uses API keys for authentication. Each API key has specific permissions that control what operations it can perform.
|
|
|
|
## API Key Format
|
|
|
|
API keys follow this format:
|
|
|
|
```
|
|
wmbly_<43-character-random-string>
|
|
```
|
|
|
|
The `wmbly_` prefix identifies the key as a Warmbly key. The remaining 43 characters are 32 random bytes encoded as base64url (no padding) — 256 bits of entropy, so brute-forcing a valid key is computationally infeasible.
|
|
|
|
Keys are stored as a SHA-256 hash; the plaintext is shown exactly once on creation. To help you spot a key in the dashboard without exposing the secret, we store the first 8 characters (`key_prefix`, e.g. `wmbly_ab`) and the last 4 characters (`key_suffix`, e.g. `wxyz`). Render them as `wmbly_ab…wxyz`.
|
|
|
|
## Using Your API Key
|
|
|
|
Include your API key in the `Authorization` header of every request:
|
|
|
|
```bash
|
|
curl -X GET "https://api.warmbly.com/api-keys" \
|
|
-H "Authorization: Bearer wmbly_abc123..." \
|
|
-H "Content-Type: application/json"
|
|
```
|
|
|
|
For mutation retries, include an `Idempotency-Key` header with a unique value per logical operation. Warmbly stores completed mutation responses for 24 hours per organization and key, then replays matching retries instead of performing the operation again.
|
|
|
|
## Key Security Best Practices
|
|
|
|
<Callout type="warn" title="Keep Your Keys Secret">
|
|
Never expose API keys in client-side code, public repositories, or logs. Treat them like passwords.
|
|
</Callout>
|
|
|
|
### Do's
|
|
|
|
- Store API keys in environment variables or secure secret managers
|
|
- Use different keys for development and production
|
|
- Restrict keys to only the permissions they need
|
|
- Set expiration dates for keys when possible
|
|
- Use IP allowlists to restrict key usage
|
|
|
|
### Don'ts
|
|
|
|
- Commit API keys to version control
|
|
- Share API keys via email or chat
|
|
- Use production keys in development
|
|
- Give keys more permissions than necessary
|
|
|
|
## Permissions
|
|
|
|
Each API key has a permissions bitmask that controls its capabilities. See the [Permissions Reference](/reference/permissions) for a complete list.
|
|
|
|
### Permission Categories
|
|
|
|
| Category | Description |
|
|
|----------|-------------|
|
|
| **Read** | View resources (emails, campaigns, contacts, etc.) |
|
|
| **Write** | Create and modify resources |
|
|
| **Bulk** | Perform bulk operations |
|
|
| **Special** | Advanced features (realtime, webhooks, API key management) |
|
|
|
|
### Example: Read-Only Key
|
|
|
|
A read-only API key might have these permissions:
|
|
|
|
```json
|
|
{
|
|
"permissions": 31
|
|
}
|
|
```
|
|
|
|
This combines:
|
|
- `READ_EMAILS` (1)
|
|
- `READ_CAMPAIGNS` (2)
|
|
- `READ_CONTACTS` (4)
|
|
- `READ_UNIBOX` (8)
|
|
- `READ_ANALYTICS` (16)
|
|
|
|
Total: 1 + 2 + 4 + 8 + 16 = 31
|
|
|
|
## IP Restrictions
|
|
|
|
You can restrict API keys to specific IPs or CIDR ranges. Entries can be bare IPs (v4 or v6) or CIDR blocks; an empty list means "any IP".
|
|
|
|
```json
|
|
{
|
|
"name": "Production Server",
|
|
"permissions": 688159,
|
|
"allowed_ips": [
|
|
"203.0.113.10",
|
|
"203.0.113.11",
|
|
"10.0.0.0/8",
|
|
"2001:db8::/32"
|
|
]
|
|
}
|
|
```
|
|
|
|
Requests from outside every listed range are rejected with `403 Forbidden`. There's a soft cap of 64 entries per key.
|
|
|
|
## Email Account Restrictions
|
|
|
|
Limit API keys to specific email accounts:
|
|
|
|
```json
|
|
{
|
|
"name": "Marketing Team",
|
|
"permissions": 127,
|
|
"allowed_email_accounts": [
|
|
"550e8400-e29b-41d4-a716-446655440000",
|
|
"6ba7b810-9dad-11d1-80b4-00c04fd430c8"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Key Expiration
|
|
|
|
Set an expiration date for temporary access:
|
|
|
|
```json
|
|
{
|
|
"name": "Contractor Access",
|
|
"permissions": 31,
|
|
"expires_at": "2024-12-31T23:59:59Z"
|
|
}
|
|
```
|
|
|
|
After expiration, the key returns `401 Unauthorized`.
|
|
|
|
## Error Responses
|
|
|
|
### 401 Unauthorized
|
|
|
|
Returned when:
|
|
- API key is missing
|
|
- API key is invalid
|
|
- API key has expired
|
|
- API key has been revoked
|
|
|
|
```json
|
|
{
|
|
"error": "Unauthorized",
|
|
"message": "Token not found."
|
|
}
|
|
```
|
|
|
|
### 403 Forbidden
|
|
|
|
Returned when:
|
|
- API key lacks required permissions
|
|
- Request IP is not in allowlist
|
|
- Email account is not in allowlist
|
|
|
|
```json
|
|
{
|
|
"error": "Forbidden",
|
|
"message": "You doesn't have access to this feature."
|
|
}
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Create an API key](/api-keys/create)
|
|
- [View all permissions](/reference/permissions)
|
|
- [Handle errors](/reference/error-codes)
|