Atlas
Guides

Choosing an Integration

Comparison tables to help you pick the right integration surface and auth mode for your Atlas deployment.

Atlas offers multiple ways to integrate and multiple authentication modes. These tables help you choose the right combination for your use case.

Widget vs SDK vs API

Atlas has three integration surfaces. Each serves a different audience and customization level.

DimensionScript Tag WidgetReact Package (@useatlas/react)TypeScript SDK (@useatlas/sdk)REST API
Use caseDrop-in chat bubble for any websiteCustom chat UI in a React/Next.js appServer-side or Node.js automationAny language, any platform
Setup effort~2 minutes — one <script> tag~15 minutes — install package, wrap in provider~10 minutes — install package, create client~5 minutes — HTTP calls with auth header
Framework requirementNone — plain HTMLReact 18+Node.js / Bun (or any JS runtime)None — any HTTP client
Auth approachdata-api-key attribute or Atlas.setAuthToken()Better Auth client or Bearer token via providerAPI key or Bearer token passed to createAtlasClient()Authorization: Bearer <key> header
CustomizationTheme (light/dark), position, accent color, logo, CSS variablesFull control — custom components, tool renderers, hooksProgrammatic — build any UI or pipeline on topFull control — raw request/response
Streaming supportYes (built-in)Yes (built-in via AI SDK)Yes (streamQuery() returns async generator)Yes (SSE on POST /api/chat)
Conversation managementAutomatic (widget handles state)Automatic (useConversations hook)Manual (conversations.list(), conversations.get())Manual (REST endpoints)
Best forMarketing sites, internal tools, quick demosProduct teams building a branded data experienceBackend services, scheduled reports, CI pipelinesNon-JS backends (Python, Go, Ruby), microservices

Not sure? Start with the script tag widget for the fastest proof-of-concept. Move to the React package when you need custom UI, or the SDK when you need server-side automation.

Quick examples

Script tag widget — one line of HTML:

<script
  src="https://your-api.example.com/widget.js"
  data-api-url="https://your-api.example.com"
  data-api-key="sk-..."
></script>

React package — wrap your app in the provider:

import { AtlasProvider, AtlasChat } from "@useatlas/react";

<AtlasProvider apiUrl="https://your-api.example.com" apiKey="sk-...">
  <AtlasChat />
</AtlasProvider>

TypeScript SDK — programmatic queries:

import { createAtlasClient } from "@useatlas/sdk";

const atlas = createAtlasClient({
  baseUrl: "https://your-api.example.com",
  apiKey: "sk-...",
});
const result = await atlas.query("How many users signed up last week?");

REST API — any language:

curl -X POST https://your-api.example.com/api/v1/query \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"question": "How many users signed up last week?"}'

Auth Modes

Atlas supports four authentication modes. The right choice depends on your deployment environment and user management needs.

DimensionNoneSimple Key (api-key)Managed (managed)BYOT (byot)
Best forLocal dev, internal tools behind a VPNHeadless integrations, CLI tools, SDKsMulti-user web apps with loginEnterprises with existing SSO (Auth0, Clerk, Okta)
Session managementNone — all requests are anonymousNone — stateless key per requestServer-side sessions (7-day expiry, renewed on activity)Stateless — JWT verified per request via JWKS
User isolationNo — all queries share one identityNo — single shared identity per keyYes — each user has their own account and historyYes — user identity extracted from JWT sub claim
Role supportNo rolesSingle role for the key (ATLAS_API_KEY_ROLE)Per-user roles (viewer, analyst, admin)Role extracted from JWT claim (configurable path)
RLS (row-level security)Not availableStatic claims only (ATLAS_RLS_CLAIMS)Per-user claims from sessionPer-user claims from JWT payload
Setup complexityZero configOne env var (ATLAS_API_KEY)2-3 env vars + internal Postgres (DATABASE_URL)2-4 env vars (JWKS URL + issuer required, audience + role claim optional)
Requires internal databaseNoNoYes (DATABASE_URL)No
Recommended forGetting started, demosAutomated pipelines, single-user toolsProduction apps with user accountsProduction apps with existing identity provider

Not sure? Use none for local development. When you're ready for production, choose managed if you want Atlas to handle user accounts, or BYOT if you already have an identity provider.

Auth mode configuration examples

None — no configuration needed:

# Just start the server — no auth env vars required
bun run dev

Simple Key:

ATLAS_API_KEY=your-secret-key-here
ATLAS_API_KEY_ROLE=analyst  # optional: viewer, analyst (default), admin

Managed:

BETTER_AUTH_SECRET=your-random-secret-at-least-32-characters-long
DATABASE_URL=postgresql://user:pass@host:5432/atlas
ATLAS_ADMIN_EMAIL=admin@example.com  # optional: first admin account

BYOT:

ATLAS_AUTH_JWKS_URL=https://your-idp.com/.well-known/jwks.json
ATLAS_AUTH_ISSUER=https://your-idp.com/
ATLAS_AUTH_AUDIENCE=your-atlas-api         # optional but recommended
ATLAS_AUTH_ROLE_CLAIM=app_metadata.role    # optional, defaults to checking "role" then "atlas_role"

Auto-detection

When ATLAS_AUTH_MODE is not set, Atlas auto-detects from environment variables in this order:

  1. ATLAS_AUTH_JWKS_URL present → BYOT
  2. BETTER_AUTH_SECRET present → Managed
  3. ATLAS_API_KEY present → Simple Key
  4. None of the above → None

Set ATLAS_AUTH_MODE explicitly to override auto-detection. Valid values: none, api-key, managed, byot. You can also set auth in atlas.config.ts.

Edit on GitHub

Demo Datasets

Pre-built demo datasets for evaluation and development.

MCP Server

Use Atlas as a Model Context Protocol server in Claude Desktop, Cursor, and other MCP clients.

On this page

Widget vs SDK vs APIQuick examplesAuth ModesAuth mode configuration examplesAuto-detectionRelated