Ragen AI API Authentication — API Keys and Headers

Every request to the Ragen AI API must include a valid Bearer token. You generate that token by creating an API key in your instance’s Settings dashboard. The key is scoped to your organization and to what it may read — one assistant, or the knowledge base — and it cannot be retrieved after it is first shown to you.

Create an API key

Follow these steps inside your Ragen instance to generate a new key:

Open API Keys

Create a new key

Click Create API Key and give the key a descriptive name.

Choose what the key can reach

Pick a scope. The whole knowledge base — the default — lets the key answer from the documents that belong to no assistant. One assistant binds the key to a single assistant, and the key is then refused for any other. The choice is made here and cannot be changed afterwards; to move a key to a different assistant, create a new one.

Configure optional settings

Enable Debug mode if you want API conversations saved as threads visible in the API threads tab. This is useful during development but should be disabled for production keys handling sensitive queries.

Copy the key immediately

Click Create. The full key is displayed only once. Copy it now and store it in a secrets manager or environment variable — only a masked version is kept for display afterward.

Your API key is a credential equivalent to a password. Never commit it to source control, log it, or expose it in client-side code. If a key is compromised, deactivate it immediately from Organization → API keys and generate a replacement. Deactivated keys cannot be reactivated.

API key format

Every Ragen API key follows this structure:

Bearer sk-<keyId>.<secret>

The sk- prefix signals that the value is an API secret key. The <keyId> portion identifies the key; the <secret> portion is the credential that authenticates the request. Both parts are required.

Passing the Authorization header

Include the key as a Bearer token in the Authorization header of every request:

curl -H "Authorization: Bearer sk-abc123.mysecret" \
     https://your-ragen-instance/v1/chat/completions

With the TypeScript SDK

The SDK reads your key from the RAGEN_API_KEY environment variable by default, so you rarely need to pass it explicitly:

import { Ragen } from '@webamigos/ragen-sdk-ts';

// Reads RAGEN_API_KEY and RAGEN_BASE_URL from the environment
const ragen = new Ragen({ apiKey: process.env.RAGEN_API_KEY });

You can also supply the key inline, but prefer the environment variable approach to avoid leaking credentials:

import { Ragen } from '@webamigos/ragen-sdk-ts';

const ragen = new Ragen({
  apiKey:  'sk-abc123.mysecret',   // prefer process.env.RAGEN_API_KEY
  baseURL: 'http://localhost:3001/v1',
});

What a key can reach

An API key is bound to one organization — every operation acts on resources inside it, and a key can never be promoted to another organization. Within that organization, the scope you chose when creating the key decides what it reads. It is a boundary, not a default: a request that disagrees with it is refused rather than obliged.

Key scope	`assistant_id` in the request	Result
One assistant	omitted	answers for that assistant
One assistant	the same assistant	answers for that assistant
One assistant	any other assistant	`403`
The knowledge base	omitted	answers from documents that belong to no assistant
The knowledge base	any assistant	`403`

Omitting assistant_id is the normal case, and it is what makes Ragen callable from clients that speak the OpenAI format, which has no field for it. The scope narrows more than the answer. A key bound to one assistant lists only that assistant from GET /v1/assistants, sees only its files from GET /v1/files, and cannot create or delete an assistant at all — including the one it is bound to, since deleting it would revoke the key’s own context. A knowledge-base key sees every assistant its organization owns, and the files that belong to none of them.

A key whose assistant is later deleted is refused rather than widened: it does not fall back to the knowledge base. Create a new key.

Whose permissions a key carries

The scope picks where a key reads. What it reads there follows the person who created it. Every retrieval made with a key — chat, chat completions, search, and the MCP tools, which forward the key to these endpoints — applies that person’s document permissions, exactly as the web app does for them: their organization role and their teams decide which files can enter a result. So a key created by a member returns only what that member can open, and a file its owner shared with nobody stays out of answers for other members’ keys. Organization admins are the exception: they can see user-owned files (see Document permissions), so a key created by an admin can retrieve such a file too. Give an agent a key created by the person it acts for, or by an account whose permissions you intend it to have — not an admin’s key by default.

The creator’s role and team memberships are read on every request, not frozen when the key is created: remove them from a team and their keys lose that team’s documents on the next call.

Debug mode

Each API key has an optional Debug mode toggle you can enable when creating the key. When debug mode is on:

Every API conversation is persisted as a thread on the server.
The saved threads appear in the API threads tab inside your Ragen instance.
This lets you inspect the full context, retrieved documents, and generated responses for each call.

Disable debug mode for production keys to avoid storing user conversations unnecessarily. You can create a separate debug key for development and keep your production key clean.

Error responses

The API returns standard HTTP status codes for authentication failures. Handle these in your application to surface clear error messages to users:

Status	Meaning
`401`	Invalid or missing API key. Check that the `Authorization` header is present and the key is correctly formatted.
`403`	API key has been deactivated. Generate a new key in Organization → API keys.
`429`	Rate limit exceeded. The SDK retries automatically; raw HTTP callers should back off and retry with exponential delay.

TypeScript SDK error classes

The SDK surfaces authentication failures as typed errors you can catch and handle:

import { RagenAuthError, RagenError } from '@webamigos/ragen-sdk-ts';

try {
  await ragen.chat.completions.create({
    assistantId: '123e4567-e89b-12d3-a456-426614174000',
    messages:    [{ role: 'user', content: 'Hello' }],
  });
} catch (err) {
  if (err instanceof RagenAuthError) {
    // HTTP 401 or 403 — bad or deactivated API key
    console.error('Authentication failed:', err.message);
  } else if (err instanceof RagenError) {
    console.error(err.status, err.code, err.message);
  } else {
    throw err;
  }
}

Getting Started

Endpoints

SDKs & Tools

Ragen AI API Authentication — API Keys and Headers

Create an API key

API key format

Passing the Authorization header

With the TypeScript SDK

What a key can reach

Whose permissions a key carries

Debug mode

Error responses

TypeScript SDK error classes

​Create an API key

​API key format

​Passing the Authorization header

​With the TypeScript SDK

​What a key can reach

​Whose permissions a key carries

​Debug mode

​Error responses

​TypeScript SDK error classes

Create an API key

API key format

Passing the Authorization header

With the TypeScript SDK

What a key can reach

Whose permissions a key carries

Debug mode

Error responses

TypeScript SDK error classes