API Keys
API keys authenticate server-to-server requests to the Synapse API. Each key is scoped to a specific set of operations and tied to a single workspace.
Key Format
| Component | Values | Description |
|---|---|---|
| Prefix | psk | Synapse Customer Communications Platform key identifier (prefix stored key) |
| Environment | live | Real email delivery via Resend |
test | Sandbox mode -- emails logged but not sent | |
| Random | 32 hex chars | Cryptographically random, unique per key |
The key prefix (psk_live_a1b2 -- first 12 characters) is stored in plaintext for fast lookup. The full key is bcrypt-hashed. Synapse never stores your key in plaintext after creation.
Scopes
Each API key has exactly one scope that determines which endpoints it can access:
| Scope | Endpoints | Use Case |
|---|---|---|
browser | POST /v1/events, POST /v1/events/batch | Client-side Browser SDK event tracking. Safe to embed in frontend code. |
data | POST /v1/events, POST /v1/send, POST /v1/contacts | Backend services sending events and transactional emails |
reporting | GET /v1/analytics/*, GET /v1/analytics/export | Dashboard integrations, BI tools, automated reports |
management | GET/POST/PUT/DELETE /v1/flows, /v1/templates, /v1/segments | CI/CD pipelines, infrastructure-as-code |
full | All endpoints | Development and testing only |
Browser SDK users: Always use a browser-scoped key in client-side code. Browser keys can only track events -- they cannot send emails, read contacts, or access any admin endpoints. If someone extracts the key from your page source, the blast radius is limited to writing events.
Avoid using full-scoped keys in production. If a data-scoped key is compromised, the attacker can send events but cannot read your templates, modify flows, or access analytics.
Creating Keys
API keys are created in the Synapse dashboard under Settings > API Keys, or via the management API:
Response
The key field is returned only in the creation response. Copy and store it immediately. You will not be able to retrieve it again.
Key Lifecycle
Revoking a Key
Revoked keys are immediately rejected. Any in-flight requests using the key will fail with 401.
Key Expiration
You can optionally set an expiration date when creating a key:
Expired keys are automatically rejected. They remain visible in the dashboard for audit purposes.
Rotation Best Practices
- Create the new key first -- Generate a replacement key with the same scope and environment.
- Deploy the new key -- Update your application configuration to use the new key. For zero-downtime rotation, your application should accept both keys during the transition window.
- Verify the new key works -- Send a test event and confirm a
202response. - Revoke the old key -- Once all services are updated, revoke the previous key.
Set a calendar reminder to rotate keys every 90 days. Use key names that include the rotation date (e.g., "Production Data Key - Q2 2026") so you can easily identify stale keys.
Environment-Specific Keys
| Environment | Behavior | Domain |
|---|---|---|
live | Emails are rendered and delivered via Resend | Events processed normally |
test | Emails are rendered and logged but not sent | Safe for development and staging |
Use test keys in your development and staging environments. The full event pipeline executes (flow matching, template rendering, email log creation) so you can verify behavior without sending real emails.
Plan Limits
Each plan has a maximum number of API keys:
| Plan | Max API Keys |
|---|---|
| Free | 3 |
| Starter | 10 |
| Growth | 25 |
| Enterprise | Unlimited |
Attempting to create a key beyond your plan limit returns a 403: