Authentication

The SDK authenticates using an API key and an org slug. Both are required for every request.

API Keys

API keys are long-lived credentials scoped to your organization. The API key UI is not yet available in the desktop or web app — API keys must currently be generated via the server's dev endpoints or provisioned by an admin.

import { CosmoClient } from '@cosmohq/sdk'

const client = new CosmoClient({
  apiKey: process.env.COSMO_API_KEY!,
  org: 'acme',  // your org slug
})

Store your API key in an environment variable — never hard-code it in source files.

How authentication works

Every request the SDK makes includes two headers:

Authorization: Bearer <apiKey>
X-Cosmo-Org: <orgSlug>

The X-Cosmo-Org header carries the org slug so the server can scope the request to the correct tenant without decoding the API key's JWT payload on every call.

Custom base URL

For self-hosted or staging environments, pass a baseUrl override:

const client = new CosmoClient({
  apiKey: process.env.COSMO_API_KEY!,
  org: 'acme',
  baseUrl: 'https://staging-api.cosmo.dev',
})

Errors

Authentication failures return a CosmoAPIError with status: 401. An incorrect org slug returns status: 403.

import { CosmoAPIError } from '@cosmohq/sdk'

try {
  await client.chat('Hello')
} catch (err) {
  if (err instanceof CosmoAPIError && err.status === 401) {
    console.error('Invalid or expired API key')
  }
}