Initial push of Plunk Next

2025-12-01 09:56:56 +01:00
parent 07cea20262
commit ff1876d580
566 changed files with 89036 additions and 28423 deletions
@@ -0,0 +1,163 @@
+---
+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: '[email protected]',
+    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: '[email protected]',
+    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": "[email protected]", "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: '[email protected]',
+    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': '[email protected]',
+    '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)