Authentication

Every Assistant Cloud request acts as a user in one workspace. Choose the browser mode that fits how a person reaches your app, or use an API key on a server that acts for a user. The dashboard keeps the policy in Settings › Access; your client supplies the credential on each request.

Choose a client mode

baseUrl is required for both browser modes. The API key client defaults to the backend host, and a non trace API key request must send a workspace id. The client recognizes configuration in this order: authToken, then apiKey, then anonymous. A configuration without one of those modes throws Invalid configuration: Must provide authToken, apiKey, or anonymous configuration.

Read anonymous sessions for visitor storage and thread claims. Use an auth provider for a signed in browser user. Use API keys only on your server.

What happens to a request

The client asks its auth strategy for an Authorization header before every request. A provider callback returning null or an empty string stops before the network request with Authorization failed. An API key client sends its bearer key, Aui-User-Id, and Aui-Workspace-Id; an anonymous client first obtains an access token.

The API reads the header in this order:

1. A value beginning sk_aui_proj_ is an API key.
2. A JWT whose algorithm is HS256, whose project id is valid, and whose issuer is that project's frontend host is an internal token.
3. Any other JWT is a provider token checked against an auth rule.
4. No header is accepted only by the anonymous session and refresh routes.

The header must be Authorization: Bearer <value>. A missing header answers 401 with Authorization header is missing, another scheme answers 401 with Authorization header must begin with "Bearer ", and a value that is neither an API key nor a JWT answers 403 with Unsupported authorization value.

After a credential is verified, its expected host must equal the request origin. An API key is bound to the backend host. A provider or internal token is bound to the project frontend host. A mismatch answers 403 "Origin does not match project ID", so a browser token cannot be replayed to another project host.

An accepted provider JWT is exchanged for the cloud's HS256 token in the Authorization response header. It carries the user, workspace, project and frontend issuer, is valid for five minutes, and is usable ten seconds before issue. The SDK caches it until 30 seconds before expiry and shares one provider token request while a refresh is in flight.

The API records the Aui-Sdk header in the background. The SDK sends its own name and version, then registered identities, on every request it makes with a credential; the anonymous token routes do not carry it. It reads the first 8 space-separated entries, valid or not, then records valid name/version entries. A matched Name claim also records the user's display name. See auth providers for both settings.

Users and workspaces

A workspace owns its threads. A request can read and write only the threads in its workspace, even when several users use the same project. Users and workspaces shows how to choose that boundary for a personal or shared application.

Authentication errors

Keep a browser client stable across renders. Creating it in useMemo, keyed to the token getter, preserves its exchanged token cache and its shared refresh request.

const cloud = useMemo(
  () => new AssistantCloud({ baseUrl, authToken }),
  [authToken, baseUrl],
);

Configure the matching auth provider rule, then restrict the browser hosts that may call the project with allowed origins.