Skip to content

API Key Management

Best practices for the full lifecycle of Synapse API keys: creation, storage, rotation, revocation, and environment isolation.

Key Lifecycle

Create → Store Securely → Use → Monitor → Rotate → Revoke Old

Creation

Create keys in the dashboard (Settings > API Keys) or via the API. Each key requires:

  • Name: A descriptive label (e.g., "Production Event Ingestion Q2 2026")
  • Scope: data, reporting, management, or full
  • Environment: live or test
bash
curl -X POST https://synapse-api.pyrx.tech/v1/workspace/api-keys \
-H "Authorization: Bearer <jwt_token>" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-H "Content-Type: application/json" \
-d '{"name": "Production Data Key", "scope": "data", "environment": "live"}'
Warning

The full API key is returned only in the creation response. Copy it immediately and store it in a secrets manager. Synapse cryptographically hashes the key and cannot retrieve the plaintext.

Secure Storage

Do

  • Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler)
  • Use different keys per environment (development, staging, production)
  • Use different keys per service or team

Do Not

  • Commit keys to version control (even in .env files if the repo is not private)
  • Log API keys in application logs
  • Share keys via email, Slack, or other unencrypted channels
  • Hardcode keys in application source code
python
# Correct: environment variable
import os
api_key = os.environ["SYNAPSE_API_KEY"]
 
# Wrong: hardcoded
api_key = "sk_live_..." # NEVER do this

Scope Best Practices

Assign the minimum scope needed for each use case:

ServiceRecommended Scope
Backend event ingestiondata
Transactional email senderdata
Analytics dashboard / BI toolreporting
CI/CD pipeline (template deployment)management
Internal admin scriptsfull (with expiration)
Development / testingfull + test environment
Tip

A compromised data-scoped key can send events but cannot read templates, modify flows, or export analytics. Scope limiting reduces blast radius.

Environment-Specific Keys

EnvironmentKey EnvironmentBehavior
DevelopmenttestEvents processed, emails logged but not sent
StagingtestFull pipeline execution without email delivery
ProductionliveFull pipeline execution with real email delivery

Always use test keys in non-production environments to prevent accidental email sends during development.

Rotation

Rotate API keys every 90 days or immediately if a key may be compromised.

Zero-Downtime Rotation

  1. Create a new key with the same scope and environment
  2. Update application configuration to use the new key
  3. Deploy the configuration change
  4. Verify the new key works (send a test event, confirm 202 response)
  5. Revoke the old key
bash
# Step 1: Create new key
curl -X POST https://synapse-api.pyrx.tech/v1/workspace/api-keys \
-H "Authorization: Bearer <jwt>" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-d '{"name": "Production Data Key - Q3 2026", "scope": "data", "environment": "live"}'
 
# Step 5: Revoke old key (after deployment)
curl -X DELETE https://synapse-api.pyrx.tech/v1/workspace/api-keys/ak_old_key_id \
-H "Authorization: Bearer <jwt>" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4"

Naming Convention

Include the rotation date or quarter in the key name:

  • "Production Data Key - Q2 2026"
  • "Staging Management Key - 2026-04"

This makes it easy to identify stale keys that need rotation.

Monitoring

Track key usage in the dashboard under Settings > API Keys:

MetricDescription
last_used_atTimestamp of the most recent request
last_used_ipIP address of the most recent request
Note

Keys that have not been used in 90+ days may be orphaned. Review and revoke unused keys to reduce your security surface.

Revocation

Revoking a key is immediate and irreversible. Any request using a revoked key receives 401 Unauthorized.

bash
curl -X DELETE https://synapse-api.pyrx.tech/v1/workspace/api-keys/ak_key_id \
-H "Authorization: Bearer <jwt>" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4"

Revoked keys remain visible in the dashboard (marked as revoked) for audit purposes.

Emergency: Compromised Key

If you suspect an API key has been compromised:

  1. Revoke the key immediately -- Do not wait for a replacement to be deployed
  2. Create a new key with the same scope
  3. Deploy the new key to all affected services
  4. Review email logs for any unauthorized sends during the compromise window
  5. Review audit logs to understand what actions the compromised key performed