API keys

API keys authenticate a server to Assistant Cloud. A key has the form sk_aui_proj_<project>_0…; the cloud stores only its SHA 256 hash and retains the final four characters as its visible suffix. The dashboard shows the plaintext key once, at creation, so copy it into your server secret store before closing the dialog.

How API keys authenticate a request

An API key is a bearer credential for https://backend.assistant-api.com. Every request also identifies who the server is acting for. Aui-User-Id defaults to __SYSTEM__ when it is not sent. Aui-Workspace-Id is required on every key request except POST /v1/traces, where it defaults to __OTLP__.

The key lookup is scoped to the project encoded in the key. A missing hash match or an expiry at or before the request time refuses the request. The API writes last_used_at in the background at most once every five minutes for each key in an isolate, so it is an activity marker rather than a record of every call.

Create and manage a key

Open Settings › API keys and select Generate API Key. A signed in member can create and revoke keys.

Copy this key now. For security reasons it won't appear again.

The page's table is newest first. It never reads or displays key material.

Revoke permanently deletes the key. It cannot authenticate another request after deletion. Creation writes an api_key.create audit entry with the name and expiry. Revocation writes api_key.delete with the same fields.

What a key can call

An API key can call the authenticated routes a browser runtime uses, while supplying its own user and workspace headers. The anonymous mint and refresh routes have their own anonymous authentication path and do not use API key authentication.

Some routes accept an API key and no browser credential. Use them only from a server.

From your code

Construct the client on your server. The API key configuration defaults to the backend host, and sends the three authentication headers on every request.

import { AssistantCloud } from "assistant-cloud";

export function accountCloud(userId: string, workspaceId: string) {
  return new AssistantCloud({
    apiKey: process.env.ASSISTANT_API_KEY!,
    userId,
    workspaceId,
  });
}

Pass the user and workspace that the request should act for, rather than treating a key as an end user identity. A server tool should have its own named key, expiry choice, and secret. This lets you revoke that tool's access without replacing another server's key.

const cloud = accountCloud(account.id, account.workspaceId);
const { threads } = await cloud.threads.list();

return Response.json({ threads });

The client sends these headers:

GET /v1/threads
Authorization: Bearer sk_aui_proj_…
Aui-User-Id: user_123
Aui-Workspace-Id: workspace_123

Request refusals

The backend host binding applies after the key is recognized. These are the authentication errors an API key request can receive.

Costs and limits

Keep API keys out of browser bundles and client environment variables. A browser request has its own frontend authentication modes, while a key request is bound to the backend host and can act in any user and workspace you put in its headers.

Troubleshooting