122 lines
4.6 KiB
Plaintext
122 lines
4.6 KiB
Plaintext
---
|
|
title: API Keys
|
|
description: How Plunk's two-key model works and how to use, rotate, and revoke keys safely
|
|
icon: Key
|
|
---
|
|
|
|
Every project in Plunk has exactly two API keys: a **public** key and a **secret** key. Both authenticate requests to the same API but cover different surfaces.
|
|
|
|
## Where to find your keys
|
|
|
|
In the dashboard, open your project and go to **Settings → API Keys**. Both keys are visible — copy them and store them in environment variables (never commit them to source control).
|
|
|
|
## The two keys
|
|
|
|
| Key | Prefix | Endpoints it can call | Where it's safe to use |
|
|
| ---------- | ------ | ---------------------------------------------------------------------------------- | --------------------------------- |
|
|
| Public | `pk_` | `POST /v1/track` only | Client-side code (browser, mobile apps) |
|
|
| Secret | `sk_` | Every other endpoint — sending email, contacts, segments, campaigns, templates, workflows, domains, billing | Server-side only |
|
|
|
|
The public key is intentionally limited so you can call `/v1/track` from a browser or mobile app to record events without exposing your project's full API surface. Anything beyond event tracking — sending emails, reading contacts, creating campaigns — requires the secret key.
|
|
|
|
The project a request belongs to is derived from the key automatically. There's no separate project ID parameter on API requests.
|
|
|
|
## Authenticating requests
|
|
|
|
Both keys use the same `Authorization: Bearer` format. Pass the key in the `Authorization` header on every request.
|
|
|
|
import {Tab, Tabs} from 'fumadocs-ui/components/tabs';
|
|
|
|
<Tabs items={['cURL', 'JavaScript', 'Python']}>
|
|
|
|
<Tab value="cURL">
|
|
|
|
```bash
|
|
curl https://next-api.useplunk.com/v1/send \
|
|
-H "Authorization: Bearer $PLUNK_SECRET_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "to": "user@example.com", "subject": "Hello", "body": "<p>Hi</p>" }'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab value="JavaScript">
|
|
|
|
```javascript
|
|
const response = await fetch('https://next-api.useplunk.com/v1/send', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': `Bearer ${process.env.PLUNK_SECRET_KEY}`,
|
|
'Content-Type': 'application/json',
|
|
},
|
|
body: JSON.stringify({
|
|
to: 'user@example.com',
|
|
subject: 'Hello',
|
|
body: '<p>Hi</p>',
|
|
}),
|
|
});
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab value="Python">
|
|
|
|
```python
|
|
import os
|
|
import requests
|
|
|
|
response = requests.post(
|
|
'https://next-api.useplunk.com/v1/send',
|
|
headers={
|
|
'Authorization': f"Bearer {os.environ['PLUNK_SECRET_KEY']}",
|
|
'Content-Type': 'application/json',
|
|
},
|
|
json={
|
|
'to': 'user@example.com',
|
|
'subject': 'Hello',
|
|
'body': '<p>Hi</p>',
|
|
},
|
|
)
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
If the key prefix doesn't match the endpoint (e.g. you use `pk_` on `/v1/send`), the API returns `401` with code `INVALID_API_KEY`.
|
|
|
|
## Rotating keys
|
|
|
|
Both keys live as a single pair. Rotating regenerates **both** keys simultaneously — there is no way to rotate one without invalidating the other.
|
|
|
|
When to rotate:
|
|
|
|
- A key has been committed to a public repository or shared with someone who shouldn't have it.
|
|
- You're offboarding a contractor or revoking a deployment's access.
|
|
- You're following a periodic rotation policy (e.g. every 90 days).
|
|
|
|
To rotate:
|
|
|
|
1. Open **Settings → API Keys** in the dashboard, or call `POST /users/@me/projects/:id/regenerate-keys`.
|
|
2. Confirm the rotation. The old keys stop working immediately.
|
|
3. Update every consumer (your backend env vars, client-side bundles, third-party integrations).
|
|
|
|
There's no grace period — plan a brief deployment window if you have multiple consumers.
|
|
|
|
## Storage best practices
|
|
|
|
- **Server keys (`sk_`)** belong in environment variables on the server (`.env.local` for development, your platform's secret store for production). Never bundle them into a frontend build.
|
|
- **Client keys (`pk_`)** can be shipped in browser code, but treat them as semi-sensitive — rotate if a malicious actor abuses your tracking endpoint.
|
|
- Use separate Plunk projects for staging and production so a leaked staging key can't touch production data.
|
|
|
|
## If a key is compromised
|
|
|
|
1. Rotate immediately (above).
|
|
2. Audit the **Activity** tab for unexpected sends, contact mutations, or campaign changes during the window the key was leaked.
|
|
3. Check **Billing → Consumption** for usage spikes that suggest the key was abused.
|
|
4. If you find unauthorized activity, contact support with the request IDs from the suspicious entries.
|
|
|
|
## API reference
|
|
|
|
- `POST /users/@me/projects/:id/regenerate-keys` — regenerate both keys for a project. The response includes the new keys.
|