Skip to Content
Platform APIAuthentication

Authenticate with a SynapseX API key

This page gets you a working credential for the SynapseX LLM API and shows you how to prove it works. At the end you will have a key in an environment variable, a verified HTTP 200 from the API, and a clear picture of the two checks — scope and credits — that run on every request.

What a SynapseX API key looks like

Keys are issued per workspace and start with sk-synapsex-. Send one as a bearer token on every request:

Authorization: Bearer sk-synapsex-YOUR-API-KEY

The key is displayed exactly once, at creation. Only a SHA-256 hash of it is stored, so a lost key cannot be recovered — it can only be replaced. Treat it like a password.

How to create an API key

In the workspace console, go to API Keys:

https://platform.synapsex.ai/dashboard/api-keys

Give the key a name, create it, and copy the value immediately.

If you are already signed in to the console in a browser session, the same thing is available programmatically:

POST https://platform.synapsex.ai/api/api-keys
Content-Type: application/json

{"name": "my-key"}

The response returns the secret once:

{
  "id": "...",
  "name": "my-key",
  "key": "sk-synapsex-YOUR-API-KEY",
  "createdAt": "..."
}

The name must be 1–100 characters. This endpoint requires a signed-in browser session — an API key cannot mint another API key.

Scopes: chat:write

Every new key is created with the scope chat:write, and chat:write is the only scope the API enforces. It is what allows a key to call POST /api/v1/chat/completions.

A key without it is rejected:

{"error":{"message":"API key does not have chat:write scope","type":"permission_error"}}

with HTTP 403. In practice you get this only if you deliberately created a key with a different scope set.

Credits are part of authentication

Authentication does not stop at the key. The workspace wallet is checked on the same code path, and a balance at or below zero is rejected with HTTP 402:

{"error":{"message":"Insufficient credits","type":"insufficient_quota"}}

This happens before any model runs, so an empty balance costs you nothing but a failed request. A valid key with no credits cannot call the API. Top up from Credits and spending.

Per-key controls

When you create a key you can give it:

  • A name — how you tell keys apart in the console list.
  • An optional spend limit — a per-key cap you can also change later.

Listing keys never returns the secret; the list shows the id, name, creation time, expiry, last-used time, scopes and limits only. Deleting a key revokes it immediately.

Verify your key works

Two calls. First, the success case:

export SYNAPSEX_API_KEY=sk-synapsex-YOUR-API-KEY
 
curl -sS -w '\nHTTP %{http_code}\n' \
  -H "Authorization: Bearer $SYNAPSEX_API_KEY" \
  https://platform.synapsex.ai/api/v1/models

A working key with credits returns HTTP 200 and a JSON body of the documented shape {"object": "list", "data": [ … ]} — see List the SynapseX models on the API.

Now the failure case, so you can recognise it in your logs. This call is real and returns exactly this body:

curl -sS -H "Authorization: Bearer sk-synapsex-INVALID" \
  https://platform.synapsex.ai/api/v1/models
{"error":{"message":"Invalid or expired API key","type":"authentication_error"}}

with HTTP 401. Omitting the header entirely returns {"error":{"message":"Missing or invalid API key","type":"authentication_error"}}, also 401.

Operational advice

  • One key per application or environment. Staging and production should never share a key — revoking one should not take down the other.
  • Store it in an environment variable named SYNAPSEX_API_KEY. This is the name the Python SDK reads automatically. Never commit a key to source control or paste it into a client-side bundle.
  • Rotate by overlapping. Create the new key first, deploy it, confirm traffic is flowing, and only then delete the old key. Deletion takes effect immediately, so deleting first means downtime.
OverviewChat completions