Overview

Authentication

confiqure.ai uses two distinct credentials. Use the right one for the right surface.

Workspace API key

A long-lived secret prefixed with cqai_. Use it from the CLI and from your backend. Never ship it to a browser.

Generate: Dashboard → Settings.
Scope: All actions on one workspace — a production key also authorizes its paired sandbox (sb-…) workspace; a sandbox key never authorizes production.
Lifetime: Until you revoke it.

Use from a backend request

POST /api/{workspaceKey}/embed-tokens
Authorization: Bearer cqai_••••••••••

The CLI persists this key to ~/.confiqure/credentials (on Windows: %APPDATA%/confiqure/credentials) after confiqure login.

Environment variables

For CI and ephemeral environments, prefer env vars over the credentials file. The CLI checks env vars first; they override anything stored on disk.

Variable	Purpose
CONFIQURE_API_KEY	Workspace API key (`cqai_…`).
CONFIQURE_WORKSPACE_KEY	Six-letter workspace slug from the dashboard URL.
CONFIQURE_API_BASE	Override the API host. Defaults to `https://api.confiqure.ai`.

Embed token

A short-lived JWT minted by your backend with the workspace API key. The browser uses this token in the iframe URL — it carries no workspace secrets and is scoped to your workspace and one end-user, not to an endpoint.

Default TTL

24 hours

Overridable via ttlSeconds.

Scope

One end user

Opens on what the screen names (records, a tool class) — never bound to one endpoint.

Identity

endUserHandle

Whatever string identifies your user.

See the Embed Token & SDK reference for the full mint contract — every claim, option, and lifecycle event.

Common pitfalls

Don't ship cqai_… to the browser.
It's a workspace-wide secret. Mint embed tokens server-side and hand only those to the browser.
Don't reuse one embed token across users.
Mint one per user session — the endUserHandle claim is what keys the saved configuration and names the user in every callback.

Last updated May 2026