Authentication & API Keys

​

Overview

​

API Key Types

​

Private Keys 🔒

• 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)

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

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

​

Public Keys 🌐

• 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

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

# 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
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

​

Key Management

​

Viewing Keys

• 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

// 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

• 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)

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

​

Test with curl (Public Key)

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

1. Check your key type and permissions
2. Ensure your key is active and not expired
3. Contact support for assistance