Authentication & API Keys
Every programmatic call — REST API or MCP — authenticates with an API key. This page covers the key format, how to generate one, the scope system, and how to use it.
The API key format
Keys look like this:
syx_live_AbCd1234EfGh5678IjKl90Mn
└── prefix ──┘└──── 24 base62 chars ────┘- Prefix
syx_live_+ 24 URL-safe base62 characters (~143 bits of entropy). - Synaptyx stores only a SHA-256 hash and a 12-character display prefix (e.g.
syx_live_AbC) — never the raw key.
A key is shown exactly once. The full value is returned only in the create response. There is no reveal endpoint (this mirrors Stripe and GitHub). If you lose it, revoke it and create a new one.
How to generate a key
In the dashboard
Open Settings → API Keys
Go to app.synaptyx.pro/dashboard/settings → API Keys.
Choose a key type
- MCP key — one click; auto-selects the
mcp:*scope (needs Pro/Scale). - Read-only key — pick which resources it can read; each toggled resource grants
its
read:(and where availablesearch:) scope. Use Advanced for the raw scope checklist.
Name it (and optionally set an expiry)
Give it a recognizable name; optionally set an ISO-8601 expiry date.
Create & copy
The full syx_live_… appears once — copy it immediately into your secret manager.
You can hold up to 25 active keys. Revoking is a soft delete — the row is kept for audit, and the key stops working immediately.
Authenticating requests
Pass the key in the Authorization header with the ApiKey scheme (not
Bearer — Bearer is reserved for session JWTs):
curl https://app.synaptyx.pro/api/v1/conversions \
-H "Authorization: ApiKey syx_live_your_key_here"| Result | Meaning |
|---|---|
200 | Authenticated and authorized |
401 Unauthorized | Missing, malformed, revoked, or expired key |
403 insufficient_scope | Valid key, but it lacks the scope this endpoint needs |
Scopes
Scopes are the permissions a key carries. There are three families:
| Scope | Grants |
|---|---|
mcp:* | Access to the MCP server |
read:<resource> | Read access to a resource — conversions, clicks, campaigns, offers, landing-pages, traffic-sources, reports, stats |
search:<resource> | Substring search — conversions, campaigns |
Search is separate from read on purpose. Substring search is a more powerful
capability, so search:conversions is its own scope — a key can search without being
able to list, or vice-versa.
Plan gating
Scopes are entitled by plan, enforced both at key creation and on every request:
| Scope family | Required plan (default workspace) |
|---|---|
mcp:* | Pro or Scale |
read:* / search:* | Pro or Scale (full v1 read access is positioned as a Scale feature) |
This means a downgrade silently narrows a key’s effective scopes without revoking it, and an upgrade re-lights them — the stored scope list never changes. (White-label tenants are entitled via their custom plan.)
Auditing
Every API-key request is logged (method, path, status, latency, IP, whether it was rate-limited) to a per-key audit feed kept for 90 days — so you can see exactly how a key is being used and spot anomalies.