Authentication

    The SDK supports three authentication modes. Choose the one that fits your use case.

    1. API Key

    Best for server-side applications, scripts, and backend services.

    typescript
    const client = new CadraClient({
  apiKey: 'sk-cad-xxxxxxxxxxxx',
  orgId: 123,
});
    Security: Never expose API keys in client-side code. Use a token provider for browser apps.

    2. Static Token

    Best for short-lived scripts or when you already have a JWT/OAuth token.

    typescript
    const client = new CadraClient({
  token: 'eyJhbGciOiJIUzI1NiIs...',
  orgId: 123,
});

    3. Token Provider

    Best for browser applications where tokens need to be refreshed dynamically.

    typescript
    const client = new CadraClient({
  tokenProvider: async () => {
    const res = await fetch('/api/cadra/token');
    const { token } = await res.json();
    return token;
  },
  orgId: 123,
  baseUrl: 'https://your-api.example.com/v1',
});

    The tokenProvider is called on the first request and automatically again after a 401 response (token refresh). The SDK retries the failed request once with the new token.

    Request Headers

    Every request automatically includes:

    HeaderValue
    AuthorizationBearer <credential>
    X-Org-IdOrganization ID
    Content-Typeapplication/json
    Idempotency-KeyAuto-generated for mutations

    Auth in Chat Components

    Browser-safe with token provider
    import { ChatConfigProvider, AgentChat } from '@cadraos/sdk/chat';

<ChatConfigProvider config={{
  baseUrl: 'https://your-api.example.com/v1',
  tokenProvider: async () => {
    const res = await fetch('/api/auth/cadra-token');
    const { token } = await res.json();
    return token;
  },
  orgId: 123,
}}>
  <AgentChat agentId="agent-uuid" />
</ChatConfigProvider>