Authentication

Authenticate every request with an API key, and understand what each permission allows.

Send your key

Put your key in the SYNTH_API_KEY header on every request to a /v1 route. Other auth headers, such as Authorization, aren't used for API keys.

curl https://backend.synthesys.app/api/v1/agents \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

A key acts on the workspace of the user who created it. All data it returns belongs to that account.

Create and manage keys

Manage keys at Settings > API Keys. You must be a workspace admin to create, reveal, revoke or delete a key.

Create: enter a name and generate the key. You can have up to 10 keys that aren't revoked.
Copy: workspace admins can copy a key again later from the same page.
Revoke: stops the key working straight away and for good. A revoked key can't be reactivated, so create a new one if you need access again.
Delete: removes the key permanently.

A key with an expiry date can't be reactivated once it expires either.

Permissions

Each key holds one or more permissions. Each level includes the levels below it, except admin, which is not available to customer accounts.

Permission	Allows	Includes
`read`	All `GET` routes, except custom functions, webhook settings and webhook deliveries
`write`	Creating and updating contacts, audiences and knowledge bases. Placing calls. Reading, saving and testing post-call webhooks. Reading and saving custom functions.	`read`
`delete`	Deleting contacts, audiences and knowledge bases	`read`, `write`
`admin`	Reserved for Synthesys platform admins. No `/v1` route requires it.	All

Each endpoint in the API reference shows the minimum permission it needs.

Your key can't do more than its owner can. If the key's owner is a viewer, write requests and reading custom functions return 403, whatever permissions the key has. If the owner's account is no longer active, every request returns 403.

Keep keys safe

Anyone with a key can act on your account, including placing paid calls.

Keep keys on your server. Never put them in browser code, mobile apps or public repositories.
Store keys in environment variables or a secrets manager, not in source code.
Use a separate key for each integration, so you can revoke one without affecting the others.
Revoke a key straight away if you think it has been exposed, then create a new one.
Never send a key in a URL. Use the header, so it stays out of logs and browser history.

Auth errors

Status	Code	Cause
`401`	`UNAUTHORIZED`	The header is missing, or the key is malformed, wrong, revoked or expired. All of these return the same response.
`403`	`FORBIDDEN`	The key lacks the permission this route needs, or the owner's role or account doesn't allow it.
`429`	`RATE_LIMIT_EXCEEDED`	The key is over its limit, or this IP address sent too many bad keys. See Rate limits.
`503`	`SERVICE_UNAVAILABLE`	We couldn't check the key. Retry after `Retry-After`, which is 5 seconds.

JSON

{
  "success": false,
  "error": "A valid API key is required. Send it in the SYNTH_API_KEY header.",
  "code": "UNAUTHORIZED",
  "requestId": "6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
  "timestamp": "2026-10-31T09:30:00.000Z"
}

See Errors for the full response format.