Project API Keys

Create scoped API keys for direct machine access to project APIs.

Key Types

Type	Prefix	Use case
Secret	syn_sk_	Server-side only. Full scope access. Shown once at creation.
Publishable	syn_pk_	Safe for client apps (React Native, browser). Limited to customer write scopes.

Endpoints

GET    /api/organizations/{organizationId}/projects/{projectId}/api-keys
POST   /api/organizations/{organizationId}/projects/{projectId}/api-keys
DELETE /api/organizations/{organizationId}/projects/{projectId}/api-keys/{keyId}

Auth Rules

• Key management endpoints require an authenticated dashboard session
• Only organization admins can create/list/revoke keys
• Created keys are project-scoped

Available Scopes

Scope	Access	Publishable
project:admin	Full project API access
chat_schemas:read	Read chat schemas
chat_schemas:write	Create/update/delete chat schemas
source_maps:read	List source maps
source_maps:write	Upload source maps
customers:read	Read customer profiles and devices
customers:write	Create/update customer profiles	Yes
customer_events:write	Record customer-scoped events	Yes
customer_devices:write	Register/update customer devices	Yes
queue_jobs:read	Read queue job status and lifecycle events
queue_jobs:write	Enqueue jobs into the shared worker queue
chat:invoke	Call /api/{accountId}/chat from a server
kb:write	Register documents for KB ingestion
kb:read	Query the knowledge base and read document status
email:send	Send transactional email via POST /api/v1/emails/send
email:sends:read	Read email send history and delivery status (where exposed by your deployment)
databases:read	Read hosted database status, credentials metadata, and backup records
databases:write	Create and update hosted database resources
databases:admin	Rotate credentials, trigger backup/restore workflows, and manage placement-sensitive actions

Secret keys only: publishable keys cannot call POST /api/v1/emails/send. Hosted database scopes are reserved for the database control-plane endpoints.

Create Key

POST /api-keys

Request Body

{
  "name": "Mobile App Client Key",
  "type": "publishable",
  "scopes": ["customers:write", "customer_events:write", "customer_devices:write"],
  "expiresAt": "2026-12-31T23:59:59.000Z"
}

type defaults to "secret" if omitted.

Response (secret key)

{
  "apiKey": {
    "id": "uuid",
    "name": "CI Deployment Key",
    "type": "secret",
    "keyPrefix": "syn_sk_9d2e4f...",
    "scopes": ["source_maps:write", "chat_schemas:read"],
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "createdAt": "2026-02-19T00:00:00.000Z"
  },
  "secret": "syn_sk_9d2e4f..."
}

secret is only returned once at creation time.

Response (publishable key)

{
  "apiKey": {
    "id": "uuid",
    "name": "Mobile App Client Key",
    "type": "publishable",
    "keyPrefix": "syn_pk_a1b2c3...",
    "scopes": ["customers:write", "customer_events:write", "customer_devices:write"],
    "createdAt": "2026-02-19T00:00:00.000Z"
  },
  "publishableKey": "syn_pk_a1b2c3..."
}

Publishable keys are returned as publishableKey and can be viewed again from the dashboard.

Using a Key

Use either header format:

Authorization: Bearer syn_pk_xxx

or

x-api-key: syn_pk_xxx

Both secret (syn_sk_) and publishable (syn_pk_) keys use the same header format.

Public Customer Endpoints

Publishable keys are designed for these CORS-enabled, rate-limited endpoints:

POST /api/{accountId}/customers/identify    (scope: customers:write)
POST /api/{accountId}/customers/track       (scope: customer_events:write)
POST /api/{accountId}/customers/devices     (scope: customer_devices:write)

See SDK API Client for client usage examples.

Revoke Key

DELETE /api-keys/{keyId}

Revocation is immediate. Revoked keys return 401 on protected APIs.