Authentication

Every AISquare request is authenticated with a workspace API key passed in the Authorization header. This page shows how to get a key, keep it safe, and use it from a server, a script, or the SDK.

Get a workspace key

An API key is scoped to a workspace and identifies who is making the call. You can mint keys two ways:

• From the dashboard. Open your workspace settings and create a key. Copy it once; it is shown only at creation.
• Programmatically, per user. Your backend registers each user through the registration API, which provisions the user and returns a key for them. This is the recommended path for platforms (see Per-user keys below).

Ingest key for the explainability SDK and proxy

The explainability surface (the SDK and multi-provider proxy) uses its own workspace ingest key, minted on the dashboard Connectors page. It looks like AIS_... and is shown once, at creation. It is not interchangeable with the platform API key above.

• SDK: export it as EXPLAINABILITY_API_KEY, with EXPLAINABILITY_GATEWAY_URL set to your workspace's base gateway URL (no path).
• Proxy: send it as the X-AISquare-Key header on every request.

Two more variables shape how SDK traces are identified (see Agent identity for the full contract):

• EXPLAINABILITY_AGENTS — a comma-separated roster, pre-registered at init so first traces route immediately. The names must equal the agent_name values used in code.
• AISQUARE_AGENT_NAME — configures policy checks and, from SDK 1.0.6, doubles as the fallback trace identity when no explicit name is set. Keep it equal to your agent_name.

Store the key as an environment variable

Keep the key out of your source. Put it in an environment variable, which is also where the SDK looks for it by default.

AISQUARE_API_KEY=aisq_live_your_key_here

Make sure the file is gitignored, then load it into your shell or process manager so the variable is available at runtime.

Authenticate a request

Pass the key as a bearer token. This works for any HTTP client, in any language.

curl -X POST https://api.aisquare.com/api/v1/aistudios/experiences/flattened/ \
  -H "Authorization: Bearer $AISQUARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "ai-research-studio" }'

Let the SDK read the key

The SDK reads AISQUARE_API_KEY from the environment, so you construct the client with no arguments and it is already authenticated. Nothing about the key appears in your code.

from aisquare import AISquare

# Reads AISQUARE_API_KEY from the environment.
client = AISquare()

experiences = client.experiences.flattened(url="ai-research-studio")
print(experiences.count)

import { AISquare } from "@aisquare/sdk";

// Reads AISQUARE_API_KEY from the environment.
const client = new AISquare();

const experiences = await client.experiences.flattened({ url: "ai-research-studio" });
console.log(experiences.count);

To use a key explicitly instead of the environment (for example, when you hold a different key per user), pass it to the constructor:

client = AISquare(api_key=user_api_key)

Per-user keys for platforms

If you are building a platform on top of AISquare, give each of your users their own key rather than sharing one workspace account. Your backend registers the user, stores their key securely, and makes calls on their behalf.

Per-user keys keep each user's data and metrics separate, which a shared account cannot do.

Tokens for browser and SSO flows

API keys cover server-to-server calls. Two other methods cover the cases keys do not.

• JWT tokens. Exchange a key at the login endpoint for an access token (valid 7 days) and a refresh token (valid 30 days). Send the access token the same way: Authorization: Bearer <access_token>. Refresh it when it expires. See Token lifecycle for the full flow.
• Cookie and OpenID. Browser apps can authenticate with a session cookie that rides along automatically; enterprises can connect SSO over OpenID.

Next steps