164 lines
3.6 KiB
Plaintext
164 lines
3.6 KiB
Plaintext
---
|
|
title: Authentication
|
|
description: Understanding API keys and authentication
|
|
---
|
|
|
|
## Two types of API keys
|
|
|
|
Each project has two API keys for different purposes:
|
|
|
|
### Secret Key (sk_*)
|
|
|
|
**Use for:** All server-side API calls
|
|
|
|
- Required for `/v1/send` (sending emails)
|
|
- Required for all dashboard API endpoints (contacts, campaigns, templates, etc.)
|
|
- Can access and modify all project data
|
|
- **Never expose in client-side code**
|
|
|
|
**Example:**
|
|
```javascript
|
|
// Server-side only
|
|
fetch('{{API_URL}}/v1/send', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': 'Bearer sk_your_secret_key',
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
to: 'user@example.com',
|
|
subject: 'Hello',
|
|
body: '<p>Your order is ready!</p>'
|
|
})
|
|
});
|
|
```
|
|
|
|
### Public Key (pk_*)
|
|
|
|
**Use for:** Client-side event tracking only
|
|
|
|
- Works **only** with `/v1/track` endpoint
|
|
- Cannot send emails or access any other endpoints
|
|
- Safe to include in frontend JavaScript
|
|
- Use for tracking user behavior from web browsers or mobile apps
|
|
|
|
**Example:**
|
|
```javascript
|
|
// Client-side safe
|
|
fetch('{{API_URL}}/v1/track', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': 'Bearer pk_your_public_key',
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
email: 'user@example.com',
|
|
event: 'button_clicked',
|
|
data: { button: 'signup' }
|
|
})
|
|
});
|
|
```
|
|
|
|
## Finding your API keys
|
|
|
|
1. Log into [Plunk dashboard]({{DASHBOARD_URL}})
|
|
2. Select your project
|
|
3. Go to **Settings > API Keys**
|
|
4. Copy the key you need
|
|
|
|
## Using API keys
|
|
|
|
All authenticated requests use the `Authorization` header with Bearer token format:
|
|
|
|
```bash
|
|
Authorization: Bearer sk_your_secret_key
|
|
```
|
|
|
|
### cURL example
|
|
|
|
```bash
|
|
curl -X POST {{API_URL}}/v1/send \
|
|
-H "Authorization: Bearer sk_your_secret_key" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"to": "user@example.com", "subject": "Test", "body": "Hello"}'
|
|
```
|
|
|
|
### Node.js example
|
|
|
|
```javascript
|
|
const PLUNK_SECRET_KEY = process.env.PLUNK_SECRET_KEY;
|
|
|
|
const response = await fetch('{{API_URL}}/v1/send', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': `Bearer ${PLUNK_SECRET_KEY}`,
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
to: 'user@example.com',
|
|
subject: 'Test',
|
|
body: 'Hello'
|
|
})
|
|
});
|
|
```
|
|
|
|
### Python example
|
|
|
|
```python
|
|
import os
|
|
import requests
|
|
|
|
PLUNK_SECRET_KEY = os.environ.get('PLUNK_SECRET_KEY')
|
|
|
|
response = requests.post(
|
|
'{{API_URL}}/v1/send',
|
|
headers={
|
|
'Authorization': f'Bearer {PLUNK_SECRET_KEY}',
|
|
'Content-Type': 'application/json'
|
|
},
|
|
json={
|
|
'to': 'user@example.com',
|
|
'subject': 'Test',
|
|
'body': 'Hello'
|
|
}
|
|
)
|
|
```
|
|
|
|
## Security best practices
|
|
|
|
### Store secret keys securely
|
|
|
|
Never commit secret keys to version control. Use environment variables:
|
|
|
|
```bash
|
|
# .env file (add to .gitignore)
|
|
PLUNK_SECRET_KEY=sk_your_secret_key
|
|
```
|
|
|
|
### Rotate compromised keys
|
|
|
|
If a secret key is exposed:
|
|
|
|
1. Go to **Settings > API Keys**
|
|
2. Click **Regenerate Secret Key**
|
|
3. Update your application with the new key
|
|
4. The old key stops working immediately
|
|
|
|
### Use the right key for the job
|
|
|
|
- **Sending emails from your backend?** → Use secret key
|
|
- **Tracking events from frontend?** → Use public key
|
|
- **Managing contacts via API?** → Use secret key
|
|
- **Building a workflow dashboard?** → Use secret key
|
|
|
|
When in doubt, if it's not `/v1/track`, you need the secret key.
|
|
|
|
## Next Steps
|
|
|
|
Now that you're authenticated, you can:
|
|
|
|
- [Send your first email](/getting-started/quick-start)
|
|
- [Explore the API](/api-reference/overview)
|
|
- [Manage contacts](/guides/contacts)
|
|
- [Create campaigns](/guides/campaigns)
|