API Key Management

Create and manage API keys for programmatic access to the Atlas API via the SDK, MCP server, or embeddable widget.

API keys provide programmatic access to the Atlas API. Use them to authenticate requests from the TypeScript SDK, MCP server, or embeddable widget without requiring interactive login.

Prerequisites

Managed auth enabled
A user with the admin role
DATABASE_URL configured (keys are stored in the internal database)

Overview

Route: /admin/api-keys

The API Keys page lists all keys for your workspace. Each row shows the key name, masked key prefix, creation date, last used timestamp, expiration status, and a Revoke action.

Creating a Key

Click Create API Key
Enter a descriptive name (e.g. "Production API", "MCP Server")
Click Create
Copy the key from the dialog — it is only shown once

Store the key immediately. Once you close the dialog, the full key cannot be retrieved. If you lose it, revoke the old key and create a new one.

The key is scoped to your current organization (workspace). In SaaS mode, each workspace manages its own keys independently.

Revoking a Key

Click the Revoke button on the key row
Confirm in the dialog

Revocation is immediate and permanent. Any application using the revoked key will receive 401 Unauthorized responses.

Using API Keys

Pass the key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-atlas.example.com/api/v1/chat

SDK

import Atlas from "@useatlas/sdk";

const atlas = new Atlas({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://your-atlas.example.com",
});

MCP Server

Set the ATLAS_API_KEY environment variable when starting the MCP server, or pass it in the MCP client configuration.

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

SaaS vs Self-Hosted

Behavior	Self-Hosted	SaaS
Key scope	Global (single workspace)	Per-workspace
Who can manage	Any admin	Workspace admins
Storage	Internal database	Internal database

The UI and workflow are identical in both modes. In SaaS deployments, keys are automatically scoped to the active workspace.

API Endpoints

All endpoints require admin authentication.

Method	Path	Description
`GET`	`/api/auth/api-key/list`	List all API keys
`POST`	`/api/auth/api-key/create`	Create a new key (returns full key once)
`POST`	`/api/auth/api-key/delete`	Revoke a key by ID