Authentication & Scopes
Synapse uses two authentication methods that map to different parts of the API. Understanding which method to use -- and which scopes to request -- is essential for secure integration.
Two Auth Methods
| Method | Used for | How it works |
|---|---|---|
| API key | Data-plane endpoints (events, contacts, sending, analytics) | X-WORKSPACE-ID + X-API-KEY headers, or Basic Auth |
| JWT | Control-plane endpoints (members, billing, workspace settings) | Authorization: Bearer <token> from dashboard session |
Data-plane endpoints are the programmatic API surface -- the endpoints your backend services call to ingest events, send emails, manage content, and read analytics. These accept API key authentication.
Control-plane endpoints manage workspace configuration: team members, billing, workspace deletion, and ownership transfer. These require a dashboard JWT and are not accessible via API key.
Some endpoints accept both methods. For example, contacts and domains endpoints work with either an API key (with appropriate scope) or a JWT. The auth badge on each API page tells you which methods are accepted.
API Key Authentication
Sending Credentials
Option A: Header-based (recommended)
Option B: Basic Auth
Option C: Query parameter (browser SDK only)
For browser sendBeacon calls that cannot set custom headers. The workspace is resolved from the key.
Scope Catalog
Each API key has a single scope that grants a set of fine-grained permissions:
data scope
For backend services that send events, upsert contacts, and trigger transactional emails.
| Permission | Description |
|---|---|
events:write | Ingest events via POST /v1/events |
contacts:write | Create and update contacts |
send:write | Send transactional emails via POST /v1/send |
reporting scope
For BI tools, dashboards, and automated report pipelines.
| Permission | Description |
|---|---|
analytics:read | Read analytics and dashboard metrics |
flows:read | List flows and flow details |
logs:read | Read email delivery logs |
contacts:read | Read contact records |
templates:read | Read email template content |
management scope
For CI/CD pipelines and infrastructure-as-code that manage CRM configuration.
| Permission | Description |
|---|---|
flows:write | Create, update, and delete flows |
templates:write | Create, update, and delete templates |
templates:read | Read email template content |
segments:write | Create, update, and delete segments |
contacts:write | Create and update contacts |
contacts:read | Read contact records |
settings:write | Update workspace settings |
full scope
Combines all permissions from data, reporting, and management. Use only in development and testing environments.
Avoid full-scoped keys in production. If a data-scoped key is compromised, the attacker can send events but cannot read your templates, export analytics, or modify flows.
Scope Presets (Common Configurations)
| Use case | Recommended scope | Why |
|---|---|---|
| Event ingestion | data | Backend sends events and upserts contacts. No read access needed. |
| Reporting / BI | reporting | Read-only access to analytics, logs, and contacts. Cannot modify anything. |
| Content management | management | Manages flows, templates, and segments. Does not send events. |
| Full data plane | full | Development and testing only. Grants all API key permissions. |
JWT Authentication (Dashboard)
JWT tokens are issued by pyrx.auth when a user logs into the Synapse dashboard. They are short-lived (15 minutes) and verified using cached JWKS public keys.
JWT authentication provides access to control-plane endpoints that API keys cannot reach:
- Members API -- invite, update roles, deactivate team members
- Billing API -- view plan, checkout, manage subscription
- Workspace management -- transfer ownership, delete workspace
Multi-Workspace Users
If a user belongs to multiple workspaces, include X-WORKSPACE-ID to specify the workspace context:
Error Responses
401 -- Authentication Failed
| Code | Cause |
|---|---|
invalid_api_key | API key is missing, revoked, expired, or does not match |
token_expired | JWT has expired (15-minute TTL) |
invalid_token | JWT signature is invalid or claims are malformed |
403 -- Authorization Failed
| Code | Cause |
|---|---|
insufficient_scope | API key scope does not include the required permission for this endpoint |
control_plane_only | Endpoint requires JWT authentication (dashboard only) -- API keys are not accepted |
insufficient_role | JWT user's role does not have the required permission |
Endpoint Auth Reference
| Endpoint group | API key | JWT | Required scope |
|---|---|---|---|
Events (/v1/events) | Yes | No | data -- events:write |
Contacts (/v1/contacts) | Yes | Yes | data or management -- contacts:write / contacts:read |
Direct Send (/v1/send) | Yes | No | data -- send:write |
Flows (/v1/flows) | Yes | Yes | reporting (read) or management (write) |
Templates (/v1/templates) | Yes | Yes | reporting (read) or management (write) |
Segments (/v1/segments) | Yes | Yes | management -- segments:write |
Analytics (/v1/analytics) | Yes | Yes | reporting -- analytics:read |
Email Logs (/v1/email-logs) | Yes | Yes | reporting -- logs:read |
Domains (/v1/workspace/domains) | No | Yes | Dashboard auth required |
Jobs (/v1/jobs) | No | Yes | Dashboard auth required |
Webhook Endpoints (/v1/workspace/webhook-endpoints) | No | Yes | Dashboard auth -- webhooks:read / webhooks:write |
Members (/v1/workspace/members) | No | Yes | Dashboard auth -- members:read / members:write |
Billing (/v1/workspace/billing) | No | Yes | Dashboard auth -- owner only |
Workspace (/v1/workspace) | No | Yes | Dashboard auth required |