Authentication

How to authenticate with the Start.chat API

The Start.chat API uses API keys to authenticate requests. You can manage your API keys in your account settings.

When to read this page

Use this page if you are integrating through the API, SDK, or CLI and need to understand how credentials are issued, scoped, and sent.

API access follows the same permission model as the product itself: keys are scoped to a server and inherit the permissions of the role they were created with.

Getting an API Key

Create an API key from Server Settings → API Keys in the app. Each key is scoped to a server and role.

For CLI usage, you can also run start login to authenticate via browser and save credentials locally. See the CLI guide for details.

API Keys

Your API key carries many privileges, so be sure to keep it secure. Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, etc.

API keys use the format sk_live_* for production keys. Each key is scoped to a specific server and role.

How auth fits together

• Use an API key for server-to-server access and scripts.
• Use start login when you want the CLI to store credentials locally.
• Use setup({ apiKey }) in the SDK when you want typed access from TypeScript.

Making Authenticated Requests

Include your API key in the Authorization header of your requests:

curl https://start.chat/api/v1/messages \
  -H "Authorization: Bearer sk_live_your_api_key"

Using the SDK

When using our TypeScript SDK, call setup with your API key, then use query and mutate for data access:

import { setup, query } from '@start-chat/sdk'

await setup({ apiKey: 'sk_live_your_api_key' })
const servers = await query.userServers()

Environment Variable

You can also set the START_API_KEY environment variable instead of passing the key directly:

export START_API_KEY=sk_live_your_api_key

The SDK and CLI will automatically use this when no key is provided explicitly.

Error Responses

If authentication fails, you’ll receive a 401 response:

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Rate Limiting

API requests use a fixed-window limit per user and resource. Hosted counters are shared across worker isolates:

Rate limit information is included in response headers:

• X-RateLimit-Limit - Request limit per window
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Unix timestamp when the window resets