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

# Authentication & API Keys

> Complete guide to Letterby API authentication, key types, and security best practices

## Overview

Letterby uses API key authentication to secure access to our API endpoints. We
offer two types of API keys designed for specific use cases, from server-side
integrations to client-side applications.

## API Key Types

### Private Keys 🔒

**Best for: Server-side applications, backend services, admin operations**

* **Full Access**: Complete CRUD operations on all endpoints
* **No Restrictions**: Can be used from any IP address or domain
* **High Security**: Must be kept secret and never exposed publicly
* **Rate Limits**: Managed by Cloudflare (same for all users)

**Example Use Cases:**

* Backend API integrations
* Server-side contact management
* Automated data synchronization
* Admin dashboard operations

```bash theme={null}
# Private key usage (server-side only)
curl -X DELETE "https://letterby.com/api/v4/contacts/123" \
  -H "apiKey: priv_your-private-key"
```

### Public Keys 🌐

**Best for: Frontend applications, client-side forms, mobile apps**

* **Limited Access**: Create contacts only (no read, update, or delete
  operations)
* **Client-Safe**: Designed to be safely embedded in frontend code
* **No Restrictions**: Can be used from any domain or origin

**Example Use Cases:**

* Signup forms on websites
* Contact creation from mobile apps
* Newsletter subscription widgets
* Lead capture forms

```bash theme={null}
# Public key usage (client-side safe)
curl -X POST "https://letterby.com/api/v4/contacts" \
  -H "Content-Type: application/json" \
  -H "apiKey: pub_your-public-key" \
  -d '{"email": "user@example.com", "listId": "your-list-id"}'
```

## Creating API Keys

1. Navigate to your [Letterby Dashboard](https://letterby.com/admin/lists)
2. Select your project
3. Go to the **Integrations** tab
4. Click **Create key**
5. Choose **Private** or **Public** based on your use case
6. Configure options:
   * **Key name**: Descriptive name for organization
   * **Expiration**: Optional automatic expiration date

## Security Best Practices

### ✅ Do's

* Use **Private keys** for server-side applications
* Use **Public keys** for client-side applications
* Set expiration dates for temporary integrations
* Regenerate keys if compromised
* Use descriptive names for key organization
* Store Private keys securely (environment variables, key management services)

### ❌ Don'ts

* Never expose Private keys in frontend code
* Don't hardcode keys in public repositories
* Avoid using Private keys in mobile apps
* Don't share keys across different applications
* Never log API keys in application logs

## Common Error Responses

| Status Code | Error                    | Description                          | Solution                                  |
| ----------- | ------------------------ | ------------------------------------ | ----------------------------------------- |
| `400`       | No API key provided      | Missing `apiKey` header              | Add `apiKey` header to request            |
| `401`       | Unauthorized request     | Invalid, expired, or inactive key    | Check key validity and status             |
| `403`       | Insufficient permissions | Public key used for non-POST request | Use Private key or switch to POST request |
| `429`       | Rate limit exceeded      | Too many requests                    | Wait and retry, or upgrade plan           |

## Key Management

### Viewing Keys

In your dashboard, you can see:

* Key type (Private/Public)
* Active/inactive status
* Expiration date (if set)
* Creation date
* Last used date

### Key Controls

* **Toggle**: Enable/disable keys instantly
* **Edit**: Update name and expiration
* **Delete**: Permanently remove keys
* **Copy**: Safely copy key values

## JavaScript/Frontend Usage

Public keys are perfect for frontend applications:

```javascript theme={null}
// Safe to use in client-side code
fetch('https://letterby.com/api/v4/contacts', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		apiKey: 'pub_your-public-key',
	},
	body: JSON.stringify({
		email: 'user@example.com',
		listId: 'your-list-id',
	}),
})
```

## Migration from Legacy Keys

If you have existing API keys created before our security enhancement:

* They continue to work with full access (backward compatibility)
* Consider migrating to Private keys for server-side use
* Create new Public keys for client-side applications
* Update your applications to use the new key types

## Testing Your Integration

### Test with curl (Private Key)

```bash theme={null}
curl -X GET "https://letterby.com/api/v4/contacts?listId=your-list-id" \
  -H "apiKey: your-private-key"
```

### Test with curl (Public Key)

```bash theme={null}
curl -X POST "https://letterby.com/api/v4/contacts" \
  -H "Content-Type: application/json" \
  -H "apiKey: your-public-key" \
  -d '{"email": "test@example.com", "listId": "your-list-id"}'
```

## Support

If you encounter issues with API key authentication:

1. Check your key type and permissions
2. Ensure your key is active and not expired
3. Contact [support](mailto:hi@letterby.com) for assistance

<Note>
  Need help choosing the right key type? **Private keys** for backends, **Public
  keys** for frontends!
</Note>