Skip to content

Managing API Keys

API keys allow external systems to interact with your Synapse workspace programmatically. You use them to ingest events, manage contacts, and pull reporting data through the API.

Who Can Manage API Keys

Only these roles can create and revoke API keys:

ActionOwnerAdminDeveloperMarketingOperationsViewer
View API keysYesYesYes------
Create API keysYesYesYes------
Revoke API keysYesYesYes------

If you don't see the API Keys page in Settings, your role does not have access. Ask an Owner or Admin to create a key for you.

Creating an API Key

  1. Go to Settings > API Keys in the dashboard sidebar.
  2. Click Create API Key.
  3. Fill in the details:
FieldDescription
NameA descriptive label (e.g., "Production Event Ingestion", "Backend Data Sync")
ScopeWhat the key is allowed to do (see Scopes below)
Environmentlive for production, test for development/staging
ExpirationOptional -- set a date when the key automatically stops working
  1. Click Create.
  2. Copy the key immediately. It is shown only once and cannot be retrieved later.
Danger

The full API key is displayed only at creation time. If you lose it, you'll need to revoke the old key and create a new one. There is no way to recover or view the key again.

Understanding Scopes

Each API key has a scope that controls which endpoints it can access. Always choose the most restrictive scope that meets your needs.

ScopeWhat It Can DoBest For
dataIngest events, create/update/delete contactsSDKs, backend integrations, data pipelines
reportingRead analytics, pull reportsBI tools, dashboards, reporting scripts
managementEverything in data + manage contacts + workspace settingsAdmin scripts, migration tools
fullComplete API access (all scopes)Internal tooling only -- avoid in production

Scope Details

data scope covers:

  • POST /v1/events -- send events
  • POST /v1/contacts -- create or update a contact
  • POST /v1/contacts/bulk -- bulk import contacts
  • PATCH /v1/contacts/{external_id} -- update a contact

management scope adds:

  • DELETE /v1/contacts/{external_id} -- delete contacts
  • All data scope endpoints

reporting scope covers:

  • Analytics and reporting read endpoints

full scope covers:

  • All of the above
Warning

Never use a full scope key in client-side code or public repositories. If you only need to send events from a frontend SDK, use a data scope key.

Key Format

Synapse API keys follow a predictable format that helps you identify them:

psk_{environment}_{32_hex_characters}

For example:

  • psk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 -- a live/production key
  • psk_test_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3 -- a test/development key

The psk_live_ or psk_test_ prefix tells you at a glance whether a key is for production or testing. The prefix is also used internally for fast key lookup, while the full key is verified against a bcrypt hash for security.

Using API Keys

API keys are sent via request headers. Synapse supports two authentication methods:

Header Authentication

Include both your workspace ID and API key as headers:

X-WORKSPACE-ID: your-workspace-id
X-API-KEY: psk_live_a1b2c3d4...

Basic Authentication

Alternatively, use HTTP Basic Auth with your workspace ID as the username and API key as the password:

Authorization: Basic base64(workspace_id:api_key)

Both methods work identically. Choose whichever is more convenient for your integration.

Revoking an API Key

When a key is compromised, no longer needed, or an employee leaves, revoke it immediately:

  1. Go to Settings > API Keys.
  2. Find the key you want to revoke.
  3. Click Revoke.
  4. Confirm the action.

Revocation takes effect immediately. Any requests using the revoked key will receive a 401 Unauthorized response.

Tip

Revoked keys are kept in the list with a "Revoked" status so you have an audit trail. You can filter the list to hide revoked keys if the list gets long.

Security Best Practices

  1. Use the narrowest scope possible. If a service only sends events, give it a data key -- not full.
  2. Use separate keys per integration. If your backend and your analytics tool both need API access, create a separate key for each. That way you can revoke one without disrupting the other.
  3. Set expiration dates for keys given to contractors or temporary integrations.
  4. Rotate keys periodically. Create a new key, update your integration, then revoke the old one.
  5. Never commit keys to version control. Use environment variables or a secrets manager.
  6. Use test environment keys during development and staging. They make it easy to identify and clean up test data.

Plan Limits

The number of API keys you can create depends on your plan. If you hit the limit, you'll see a "plan limit reached" error. Revoke unused keys or upgrade your plan to create more.

Next Steps