Authentication

The SDK authenticates with the Credo AI platform using API keys. You can configure authentication via environment variables or by passing credentials directly to the client.

Environment Variables

The recommended approach is to set environment variables:

Variable	Required	Description
`CREDOAI_API_KEY`	Yes	Your API key from the Credo AI dashboard
`CREDOAI_API_URL`	No	API endpoint URL. Defaults to `https://api.credo.ai`
`CREDOAI_TENANT`	Yes	Your organization's tenant identifier

Setting Environment Variables

In your shell:

export CREDOAI_API_KEY="your-api-key"
export CREDOAI_API_URL="https://api.credo.ai"
export CREDOAI_TENANT="your-tenant"

In a .env file:

CREDOAI_API_KEY=your-api-key
CREDOAI_API_URL=https://api.credo.ai
CREDOAI_TENANT=your-tenant

Programmatically:

Python
TypeScript

import os

os.environ["CREDOAI_API_KEY"] = "your-api-key"
os.environ["CREDOAI_API_URL"] = "https://api.credo.ai"
os.environ["CREDOAI_TENANT"] = "your-tenant"

process.env.CREDOAI_API_KEY = "your-api-key";
process.env.CREDOAI_API_URL = "https://api.credo.ai";
process.env.CREDOAI_TENANT = "your-tenant";

Explicit Configuration

You can also pass credentials directly to the client:

Python
TypeScript

from credoai import CredoAI

client = CredoAI(
    api_key="your-api-key",
    base_url="https://api.credo.ai",
    tenant="your-tenant"
)

import { createCredoAIClient } from '@credo-ai/sdk';

const client = createCredoAIClient('your-tenant', {
  apiKey: 'your-api-key',
  baseURL: 'https://api.credo.ai',
});

warning

Avoid hardcoding credentials in your source code. Use environment variables or a secrets manager for production deployments.

Using the SDK in a browser

The TypeScript SDK runs isomorphically — it works in Node.js and in the browser. It does not refuse browser runtimes when configured with an API key, and that is a sharp edge to be aware of.

Your API key will be leaked if you ship it to the browser

If you initialize the client with apiKey in code that ends up in a browser bundle, the key is embedded in the JavaScript served to every visitor. Anyone can extract it via DevTools or a network capture and use it to impersonate your tenant. Never do this on a public, internet-facing page.

Acceptable use — authorized internal frontends. If your frontend is not exposed to the public internet (for example, a VPN-only internal tool, or an SSO-gated admin dashboard on a private network) and every human who can reach the page is already authorized at a level equivalent to holding the key, direct API-key use is a reasonable trade-off.

Preferred patterns for internet-facing apps:

(a) Proxy through your backend. Keep the API key server-side and expose only the endpoints your app needs. Next.js server components and route handlers are a natural fit — credentials never reach the client bundle.
(b) Short-lived bearer tokens. Have your backend exchange the API key for a short-lived token and pass it to the client via createCredoAIClient('tenant', { token }).

Server-side only (Next.js server component or Node backend) — recommended
import { createCredoAIClient } from '@credo-ai/sdk';

// Runs on the server. process.env.CREDOAI_API_KEY never reaches the browser.
const client = createCredoAIClient(process.env.CREDOAI_TENANT!, {
  apiKey: process.env.CREDOAI_API_KEY!,
});

const { data } = await client.useCases.list();

Authorized internal frontend (not internet-exposed) — use with care
import { createCredoAIClient } from '@credo-ai/sdk';

// WARNING: only acceptable on a private/SSO-gated frontend. The apiKey below
// will be visible to anyone who loads this bundle.
const client = createCredoAIClient(import.meta.env.VITE_CREDOAI_TENANT, {
  apiKey: import.meta.env.VITE_CREDOAI_API_KEY,
});

Obtaining API Keys

Log in to the Credo AI dashboard
Navigate to Settings > API Keys
Click Create API Key
Copy the generated key and store it securely

Verifying Authentication

After configuring credentials, verify the connection:

Python
TypeScript

from credoai import CredoAI

client = CredoAI()

# Test the connection
ping = client.system.ping()
print(f"Connection successful: {ping.message}")

import { createCredoAIClient } from '@credo-ai/sdk';

const client = createCredoAIClient('your-tenant');

// Test the connection
const { data, error } = await client.system.ping();
if (error) {
  console.error('Connection failed:', error.status);
} else {
  console.log('Connection successful:', data.status);
}

Authentication Errors

If authentication fails:

Python
TypeScript

from credoai import CredoAI
from credoai.auth import AuthenticationError

try:
    client = CredoAI()
    client.system.ping()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")

import { createCredoAIClient, isCredoAIError } from '@credo-ai/sdk';

const client = createCredoAIClient('your-tenant');
const { data, error } = await client.system.ping();

if (error && isCredoAIError(error)) {
  if (error.status === 401) {
    console.error('Authentication failed:', error.body);
  }
}

Common causes:

Invalid or expired API key
Missing required environment variables
Incorrect tenant identifier

Environment Variables​

Setting Environment Variables​

Explicit Configuration​

Using the SDK in a browser​

Obtaining API Keys​

Verifying Authentication​

Authentication Errors​

Next Steps​