> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Permissions
> Set Lettr API key permission levels, choosing Full Access, Sending Only, or custom scopes to control access to API resources
When creating an API key, you assign a permission level that controls which API endpoints the key can access. Lettr supports two dashboard permission levels — **Full Access** and **Sending Only** — plus a **Custom** scope system available via the API.
## Permission Levels
### Full Access
Full Access keys provide complete access to all API endpoints and operations:
* Send emails via API
* List and retrieve sent email details
* Access and manage email templates
* Create, verify, and delete sending domains
* Configure and manage webhooks
* List projects
**Use Full Access keys for:**
* Backend services that need complete platform control
* Administrative tools and dashboards
* CI/CD pipelines that manage domains and templates
* Internal tools requiring access to all resources
### Sending Only
Sending Only keys are restricted to email sending operations only. Requests to any other endpoint will be rejected with a `403 Forbidden` response:
```json theme={null}
{
"message": "Your API key does not have the required permissions for this action.",
"error_code": "insufficient_scope"
}
```
**Use Sending Only keys for:**
* Production applications that only send transactional emails
* Third-party integrations that don't need administrative access
* Services where you want to limit the blast radius of a potential key compromise
### Custom
Custom scopes provide fine-grained access control by letting you specify exactly which operations a key can perform. Custom scopes are currently available via the API and DynamoDB — a dashboard UI for selecting individual scopes is coming soon.
#### Available Scopes
| Scope | Description |
| ----------------- | -------------------------------------------------------- |
| `emails:send` | Send emails via API |
| `emails:read` | List and retrieve sent email details and events |
| `templates:read` | List and retrieve templates |
| `templates:write` | Create, update, and delete templates |
| `domains:read` | List and retrieve domains |
| `domains:write` | Create, verify, and delete domains |
| `webhooks:read` | List and retrieve webhooks |
| `webhooks:write` | Create, update, and delete webhooks |
| `projects:read` | List projects |
| `sms:send` | Send SMS messages |
| `whatsapp:send` | Send WhatsApp messages |
| `audience:read` | List and retrieve contacts, lists, and segments |
| `audience:write` | Create, update, and delete contacts, lists, and segments |
The **Full Access** preset includes all 13 scopes. The **Sending Only** preset includes `emails:send`, `sms:send`, and `whatsapp:send`.
**Use Custom keys for:**
* Template management services that only need `templates:read` and `templates:write`
* Webhook automation tools that only need `webhooks:read` and `webhooks:write`
* Audience management integrations that need `audience:read` and `audience:write` without sending permissions
* Monitoring dashboards that only need read scopes (`emails:read`, `domains:read`, etc.)
## Creating Keys with Specific Permissions
### Via the Dashboard
1. Navigate to **Settings** > **API Keys**
2. Click **Create API Key**
3. Enter a descriptive name
4. Select the permission level:
* **Full Access** — Complete access to all endpoints
* **Sending Only** — Restricted to email, SMS, and WhatsApp sending
* ~~**Custom** — Select individual scopes (coming soon to the dashboard; available via API)~~
5. Configure optional IP restrictions
6. Click **Create**
## IP Restrictions
In addition to permission levels, you can further secure your API keys by restricting them to specific IP addresses. This provides defense in depth — even if a key is compromised, it cannot be used from unauthorized locations.
### Configuring IP Restrictions
When creating or editing an API key, you can specify allowed IP addresses in the **Allowed IPs** field:
```
203.0.113.50, 198.51.100.0/24, 10.0.0.1
```
### Supported Formats
| Format | Example | Description |
| ---------------- | -------------------- | -------------------------------------------------------- |
| Single IP | `203.0.113.50` | Allow a single IP address |
| CIDR notation | `198.51.100.0/24` | Allow a range of 256 IPs (198.51.100.0 - 198.51.100.255) |
| Multiple entries | `10.0.0.1, 10.0.0.2` | Comma-separated list of IPs or ranges |
### CIDR Notation Reference
| CIDR | IP Range Size | Example |
| ----- | -------------- | ------------------------- |
| `/32` | 1 IP | Single host |
| `/24` | 256 IPs | 10.0.0.0 - 10.0.0.255 |
| `/16` | 65,536 IPs | 10.0.0.0 - 10.0.255.255 |
| `/8` | 16,777,216 IPs | 10.0.0.0 - 10.255.255.255 |
If no IP restrictions are configured, the API key can be used from any IP address. We recommend configuring IP restrictions for production keys.
### IP Restriction Errors
When a request is made from a non-whitelisted IP:
```json theme={null}
{
"message": "Access denied. Your IP address is not allowed."
}
```
**HTTP Status**: `403 Forbidden`
## Updating Key Permissions
You can change the permission level of an existing API key at any time:
1. Navigate to **Settings** > **API Keys**
2. Click the actions menu (three dots) next to the key
3. Select **Edit**
4. Update the permission level
5. Click **Save**
Permission changes take effect immediately. If you downgrade a key from Full Access to Sending Only, any non-sending API requests using that key will be rejected right away.
## Security Recommendations
Use different API keys for development, staging, and production environments. This allows you to revoke keys independently and track usage per environment.
```
Production Web Server - Full Access
Staging Environment - Full Access
Development - Full Access
CI/CD Pipeline - Full Access
```
For maximum security, restrict production API keys to your server's IP addresses or IP ranges. This adds a layer of protection even if a key is compromised.
Review which keys are being used and their access patterns. Revoke any keys that are no longer needed or show suspicious activity.
Use descriptive names that clearly indicate each key's purpose, environment, and owner. This makes it easier to manage keys over time.
## Managing Multiple Keys
For larger organizations or complex deployments, consider creating separate keys for:
| Purpose | IP Restrictions |
| ------------------------ | ----------------------- |
| Production email sending | Production server IPs |
| Admin dashboard | Office IP range |
| CI/CD pipeline | CI service IPs |
| Monitoring service | Monitoring service IPs |
| Development testing | None (or developer IPs) |
This approach provides:
* **Isolation**: Compromise of one key doesn't affect others
* **Traceability**: Clear audit trail of which system performed which action
* **Flexibility**: Independent rotation and revocation schedules
## Next Steps
Learn how to create and manage API keys
Start sending emails with your API key