Authentication

Use API keys to authenticate server-to-server requests to andibase.

You can either create a key manually in the app or start a customer approval flow for an agent and exchange the approved device code for a workspace key.

Embedded apps use a separate runtime-key flow described below. Those keys are still Better Auth API keys, but they are short-lived, server-issued, and intended to stay in memory only.

Agent login flow

Agents can start a browser-based customer approval flow without asking the user to dig through the app first.

1. Call POST /api/agent/auth/requests.
2. Show the returned userCode or verificationUriComplete to the customer.
3. The customer signs in at /agent-login and approves one workspace.
4. Poll POST /api/agent/auth/exchange with the returned deviceCode.
5. Once approved, the response includes a workspace-scoped API key secret at apiKey.key.
6. Persist that key securely and reuse it. Do not send the user through login again unless the key was revoked or intentionally expired.

Example start request:

curl "https://andibase.com/api/agent/auth/requests" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "Claude",
    "agentDescription": "Inspect and update workspace data",
    "role": "admin"
  }'

If you omit role, agent login defaults to admin.

How authentication works

Create an API key from your workspace in the app:

1. Open the workspace you want to access.
2. Go to API Keys.
3. Create a key and choose the role it should have.
4. Copy the secret immediately. You will only see it once.

Each API key is scoped to the workspace where it was created. When you send the key, the API resolves that workspace from the key itself.

Embedded apps

Apps published at /w/:handle/apps/:handle require a signed-in session and workspace membership.

The iframe uses the normal first-party session cookie. It does not receive a runtime API key. Instead it calls the API through:

• window.andibase.fetch(path, init?)

That helper:

1. Sends credentials: "include".
2. Adds x-workspace-handle automatically for the app workspace.
3. Does not inject an Authorization header.

Send the key in the Authorization header

Use the key as a bearer token:

curl "https://andibase.com/api/data-definitions" \
  -H "Authorization: Bearer $ANDI_API_KEY"

For clients that cannot send bearer tokens, x-api-key: <key> is also accepted, but Authorization: Bearer <key> is the recommended format.

Store the key securely

Do not hardcode API keys in source files or commit them to git.

Store the key in a secure environment variable such as ANDI_API_KEY:

export ANDI_API_KEY="andi_live_..."

Then read it from your server runtime:

const apiKey = process.env.ANDI_API_KEY;

const response = await fetch("https://andibase.com/api/data-definitions", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

That guidance applies to manual and agent-login API keys.

Roles

When you create a key, you assign one of the hardcoded roles:

• admin: full workspace access. This is the default for manual API keys and agent-login keys.
• editor: read and write access for apps, data, and files, plus workspace read access.
• viewer: read-only access across apps, data, files, and workspace metadata.

The API still enforces permissions internally. If a key does not have the required capability, the API returns 403 with a JSON body that names the missing permission.

Workspace behavior

API keys are already bound to one workspace, so you do not need to send a workspace header with bearer-token requests.

That makes them a good fit for backend services, workers, scripts, and integrations running outside the app.

Recommendations

• Use a different API key per environment or integration.
• Grant the smallest role that fits the integration.
• Rotate keys if they are exposed or no longer needed.
• Revoke keys from the workspace API Keys page when an integration is retired.