Authentication

The Syntheia API uses API key authentication. Every request must include these headers:

Header	Required	Description
x-api-key	Yes	Your API key (no prefix — just the raw key)
x-workspace-id	Yes	The workspace the request targets
x-app-name	Yes	An identifier for your application (any string)

Generating an API key

1. Log in to your Syntheia app at https://app.your-domain.com (the domain you were given access to)
2. Go to Settings → Developers → API Keys
3. Click Generate new key
4. Give your key a name (e.g. production, staging) and copy it immediately

info

Your API key is only shown once at creation time. Store it in a secrets manager or environment variable.

Finding your workspace ID

Your workspace ID is visible in the Syntheia app URL (and under Settings → Developers). It's the value you pass in the x-workspace-id header on every request.

Using your key

Pass your key in the x-api-key header on every request, along with x-workspace-id:

curl https://api.your-domain.com/documents/list \
  -H "x-api-key: sk_live_xxxxxxxxxxxx" \
  -H "x-workspace-id: 1024" \
  -H "x-app-name: my-integration" \
  -H "Content-Type: application/json" \
  -d '{"limit": 25, "offset": 0}'

Environment variables

The recommended pattern is to load your key from environment variables:

TypeScript

const response = await fetch('https://api.your-domain.com/documents/list', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SYNTHEIA_API_KEY,
    'x-workspace-id': process.env.SYNTHEIA_WORKSPACE_ID,
    'x-app-name': 'my-app',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 25, offset: 0 }),
});

Python

import os, requests

headers = {
    "x-api-key": os.environ["SYNTHEIA_API_KEY"],
    "x-workspace-id": os.environ["SYNTHEIA_WORKSPACE_ID"],
    "x-app-name": "my-app",
}
response = requests.post(
    "https://api.your-domain.com/documents/list",
    headers=headers,
    json={"limit": 25, "offset": 0},
)

Error responses

An invalid or missing key returns 401 Unauthorized:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

A missing or invalid x-workspace-id returns 400 Bad Request.

Key rotation

To rotate a key:

1. Generate a new key in Settings → Developers → API Keys
2. Update your integration to use the new key
3. Delete the old key once traffic has fully migrated

Security best practices

• Never hardcode keys in source code or commit them to git
• Use separate keys per environment (development, staging, production)
• Set the x-app-name header to something identifiable — it appears in your usage logs
• Rotate keys immediately if you suspect they have been compromised