Authentication

All API requests require authentication via Bearer token in the Authorization header.

API Keys

Generate API keys from the Developer Dashboard at synthraai.dev/dashboard

Key Format

synthra_live_abc123def456
synthra_test_xyz789ghi012

live_ prefix for production keys
test_ prefix for development keys

Using API Keys

Include the API key in the Authorization header:

curl --request GET \
  --url https://api.synthra.ai/v1/sessions \
  --header 'Authorization: Bearer synthra_live_abc123def456'

Key Management

Creating Keys

POST /v1/keys

{
  "name": "Production API Key",
  "scopes": ["read:sessions", "write:messages"],
  "expiresAt": "2025-03-08T00:00:00Z"
}

Revoking Keys

DELETE /v1/keys/{keyId}

Rotating Keys

POST /v1/keys/{keyId}/rotate

Returns a new key while keeping the old key active for 24 hours.

Scopes

Control API access with granular scopes:

Scope	Description
`read:sessions`	View session details
`write:sessions`	Create and delete sessions
`read:messages`	View message history
`write:messages`	Send messages
`read:analytics`	Access analytics data
`admin`	Full account access

Security Best Practices

Environment Variables

const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY
});

Key Rotation

Rotate keys every 90 days for security.

Least Privilege

Grant only required scopes to each key.

Monitoring

Monitor key usage in the dashboard for suspicious activity.

Never expose API keys in client-side code, public repositories, or logs. If a key is compromised, revoke it immediately.

Test keys are limited to 100 requests per day and cannot access production data.

Introduction

Session Operations

Message Operations

Analytics

API Keys

Key Format

Using API Keys

Key Management

Creating Keys

Revoking Keys

Rotating Keys

Scopes

Security Best Practices

Environment Variables

Key Rotation

Least Privilege

Monitoring

​API Keys

​Key Format

​Using API Keys

​Key Management

​Creating Keys

​Revoking Keys

​Rotating Keys

​Scopes

​Security Best Practices

​Environment Variables

​Key Rotation

​Least Privilege

​Monitoring

API Keys

Key Format

Using API Keys

Key Management

Creating Keys

Revoking Keys

Rotating Keys

Scopes

Security Best Practices

Environment Variables

Key Rotation

Least Privilege

Monitoring