Authentication

All requests to the Synaptiq API must be authenticated using a Bearer token. API keys are managed from your Synaptiq dashboard and scoped to control access levels across your organization.

Base URL

All API requests are made to:

https://synaptiqintel.com/api/v1

Generating API Keys

1. Log in to your Synaptiq Dashboard.
2. Navigate to Settings > API Keys.
3. Click Create New Key.
4. Enter a descriptive name (e.g., "Production CRM Integration").
5. Select the appropriate scope for the key.
6. Click Generate. Copy the key immediately — it will not be shown again.

Using Your API Key

Include your API key in the Authorization header of every request:

curl https://synaptiqintel.com/api/v1/leads \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

All API requests must be made over HTTPS. Requests over plain HTTP will be rejected.

Key Scopes

Each API key is assigned a scope that determines what operations it can perform.

| Scope | Description | Allowed Methods | |---------|-----------------------------------------------------------------------------|----------------------------| | read | Read-only access to leads, conversations, and analytics. | GET | | write | Read and write access. Can create and update leads, send chat messages. | GET, POST, PATCH | | admin | Full access including key management, webhook configuration, and deletions. | GET, POST, PATCH, DELETE |

When creating integrations, always use the most restrictive scope that meets your needs.

Scope Examples

A read scoped key can:

• List and retrieve leads
• Fetch conversation history
• Query analytics endpoints

A write scoped key adds the ability to:

• Create and update leads
• Send chat messages
• Trigger workflow actions

An admin scoped key adds the ability to:

• Delete leads and conversations
• Manage webhook subscriptions
• Create and revoke other API keys
• Modify organization settings

Key Rotation

Synaptiq supports zero-downtime key rotation to keep your integrations secure:

1. Navigate to Settings > API Keys in the dashboard.
2. Click the Rotate button next to the key you want to replace.
3. A new key is generated immediately. The old key enters a grace period of 24 hours during which both keys are valid.
4. Update your applications to use the new key.
5. After the grace period expires, the old key is automatically revoked.

You can also manually revoke the old key before the grace period ends by clicking Revoke Old Key.

# Verify your new key works before the old one expires
curl https://synaptiqintel.com/api/v1/leads \
  -H "Authorization: Bearer sk_live_NEW_KEY_HERE" \
  -w "\nHTTP Status: %{http_code}\n"

Environment-Specific Keys

Synaptiq provides separate key prefixes for each environment:

| Prefix | Environment | Description | |---------------|-------------|------------------------------------------------| | sk_live_ | Production | Operates on real data. Use in production only. | | sk_test_ | Sandbox | Operates on test data. Safe for development. |

Test keys interact with an isolated sandbox environment. Leads, conversations, and analytics created with test keys do not affect your production data.

Security Best Practices

• Never expose keys in client-side code. API keys should only be used in server-side applications or secure backend services.
• Use environment variables. Store keys in environment variables rather than hardcoding them in source files.
• Rotate keys regularly. Rotate production keys at least every 90 days.
• Use the minimum scope required. A read-only integration should never use an admin-scoped key.
• Monitor key usage. Review the API Key Activity log in your dashboard to detect unusual patterns.
• Revoke compromised keys immediately. If a key is accidentally exposed, revoke it from the dashboard without delay.

# Example: loading your API key from an environment variable
export SYNAPTIQ_API_KEY="sk_live_abc123def456ghi789jkl012mno345"

curl https://synaptiqintel.com/api/v1/leads \
  -H "Authorization: Bearer $SYNAPTIQ_API_KEY"

Error Responses

If authentication fails, the API returns one of the following errors:

| Status Code | Error | Description | |-------------|------------------------|-------------------------------------------------| | 401 | unauthorized | No API key provided or the key is invalid. | | 403 | forbidden | The API key does not have the required scope. |

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Provide a valid Bearer token in the Authorization header.",
    "doc_url": "https://synaptiqintel.com/docs/api-reference/authentication"
  }
}

Rate Limits by Key Scope

API keys are subject to rate limits based on their scope and your plan tier. See Rate Limits and Error Codes for full details.

| Scope | Requests per Minute (Starter) | Requests per Minute (Pro) | Requests per Minute (Enterprise) | |---------|-------------------------------|---------------------------|----------------------------------| | read | 120 | 600 | 3,000 | | write | 60 | 300 | 1,500 | | admin | 30 | 150 | 750 |

Next Steps

• Chat API — Send messages and manage AI conversations.
• Leads API — Create and manage leads programmatically.
• Webhooks — Receive real-time event notifications.