Authentication

Synapse supports two authentication methods depending on your use case: API keys for server-to-server integration and JWT tokens for dashboard access.

API Key Authentication

Use API keys when integrating your backend services with the Synapse API. Three authentication methods are supported:

Option A: Header-based (recommended)

Send your workspace ID and API key as separate headers:

Header	Description	Example
`X-WORKSPACE-ID`	Your workspace UUID	`ws_k7x9m2p4`
`X-API-KEY`	Your API key	`psk_live_a1b2c3d4e5f6...`

bash

curl -X POST https://synapse-api.pyrx.tech/v1/events \

-H "Content-Type: application/json" \

-H "X-WORKSPACE-ID: ws_k7x9m2p4" \

-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890" \

-d '{"event_name": "signup", "external_id": "user_123", "attributes": {}}'

Option B: Basic Auth

Encode workspace_id:api_key as Base64 in the Authorization header:

bash

curl -X POST https://synapse-api.pyrx.tech/v1/events \

-H "Content-Type: application/json" \

-H "Authorization: Basic $(echo -n 'ws_k7x9m2p4:psk_live_a1b2c3d4e5f67890abcdef1234567890' | base64)" \

-d '{"event_name": "signup", "external_id": "user_123", "attributes": {}}'

Option C: Query parameter (SDK only)

For browser sendBeacon calls that cannot set headers, pass the API key as a query parameter:

POST https://synapse-events.pyrx.tech/v1/events?api_key=psk_live_a1b2c3d4e5f67890abcdef1234567890

API keys follow the format psk_{environment}_{random_hex_32}:

psk -- prefix identifying this as a Synapse Customer Communications Platform key (prefix stored key)
{environment} -- either live (real email delivery) or test (sandbox mode, emails logged but not sent)
{random_hex_32} -- 32 characters of cryptographically random hex

Warning

API keys are shown only once at creation time. Store them securely in environment variables or a secrets manager. Synapse stores only a bcrypt hash of the key -- we cannot retrieve the plaintext for you.

API Key Scopes

Each key is scoped to limit what it can access:

Scope	Permitted Endpoints
`data`	Event ingestion (`POST /v1/events`), contact upsert, direct send (`POST /v1/send`)
`reporting`	Analytics read (`GET /v1/analytics/*`), campaign stats, CSV export
`management`	Flows, templates, segments CRUD
`full`	All of the above

Tip

Use the most restrictive scope possible. A backend service that only sends events should use a data-scoped key, not full.

JWT Authentication

The Synapse dashboard uses JWT (JSON Web Token) authentication for interactive sessions. JWTs are issued by pyrx.auth and verified by Synapse using cached JWKS public keys.

Send the token in the Authorization header:

bash

curl https://synapse-api.pyrx.tech/v1/flows \

-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..."

JWT Claims

json

{

"sub": "<user_uuid>",

"tid": "<auth_tenant_uuid>",

"email": "[email protected]",

"name": "Jane Doe",

"iat": 1711900800,

"exp": 1711901700

}

Claim	Description
`sub`	The pyrx.auth user ID (mapped to `tenant_members.auth_user_id`)
`tid`	The pyrx.auth tenant UUID (shared across all PYRX Customer Communications Platform users -- NOT the CRM workspace ID)
`email`	User's email address
`name`	Display name
`iat`	Issued-at timestamp
`exp`	Expiration timestamp

Multi-Workspace Users

A single user can belong to multiple Synapse workspaces. When using JWT auth, include the X-WORKSPACE-ID header to specify which workspace context to use:

bash

curl https://synapse-api.pyrx.tech/v1/flows \

-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..." \

-H "X-WORKSPACE-ID: ws_k7x9m2p4"

If omitted, the API defaults to the user's most recently accessed workspace.

When to Use Each Method

Use Case	Method	Headers
Backend event ingestion	API Key	`X-WORKSPACE-ID` + `X-API-KEY`
Transactional email sending	API Key	`X-WORKSPACE-ID` + `X-API-KEY`
Dashboard UI requests	JWT	`Authorization: Bearer <token>`
CI/CD or scripts	API Key	`X-WORKSPACE-ID` + `X-API-KEY`
Analytics export automation	API Key (`reporting` scope)	`X-WORKSPACE-ID` + `X-API-KEY`

Error Responses

Status	Code	Description
`401`	`invalid_api_key`	The API key is missing, revoked, or does not match any active key
`401`	`token_expired`	The JWT has expired (15-minute TTL)
`401`	`invalid_token`	The JWT signature is invalid or claims are malformed
`403`	`insufficient_scope`	The API key does not have the required scope for this endpoint
`403`	`workspace_mismatch`	The API key does not belong to the specified workspace

json

{

"detail": "API key does not have 'management' scope required for this endpoint",

"code": "insufficient_scope"

}