Authentication

Every API request is authenticated with a bearer API key sent in the Authorization header:

curl https://api.assistloop.ai/api/public/v1/ai-models \
  -H "Authorization: Bearer $ASSISTLOOP_API_KEY"

Treat API keys like passwords. The full key is shown only once, at creation time — store it in a secret manager. Anyone with the key can act on your organization within the key's scopes.

Creating an API key

API keys are created and revoked from your dashboard (Settings → API Keys). Creating a key requires that you are the organization owner on a premium or active AppSumo plan.

When you create a key you choose:

A name (up to 100 characters) to identify the key.
One or more scopes (see below).
An expiry: either a future date (YYYY-MM-DD) or lifetime for a non‑expiring key.

API keys are isolated to the API. A key cannot call the first‑party dashboard API (/api/v1/*) — including the API‑key management endpoints. This prevents a narrowly‑scoped key from minting a broader one. Manage keys from the dashboard with your logged‑in session.

Scopes

A key only grants the scopes you assign to it. Each endpoint requires a specific scope; calling an endpoint without the matching scope returns 403 insufficient_scope.

Scope	Grants
`agent:read`	List and read agents; list AI models.
`agent:create`	Create agents.
`agent:edit`	Update agents (name, description, model, intervention settings).
`agent:delete`	Delete agents.
`source:read`	List/read training sources; read crawl results and training‑job status.
`source:create`	Create training sources; start crawls.
`source:edit`	Retrain training sources.
`source:delete`	Delete training sources.

Least privilege

Grant only the scopes a key needs. A read‑only analytics integration should hold only agent:read and source:read; a training pipeline that never deletes anything does not need source:delete.

Per‑endpoint scope matrix

Endpoint	Method	Scope
`/ai-models`	`GET`	`agent:read`
`/organizations/{org}/agents`	`GET`	`agent:read`
`/organizations/{org}/agents`	`POST`	`agent:create`
`/agents/{agent}`	`GET`	`agent:read`
`/agents/{agent}`	`PATCH`	`agent:edit`
`/agents/{agent}`	`DELETE`	`agent:delete`
`/agents/{agent}/sources`	`GET`	`source:read`
`/agents/{agent}/sources/{source}`	`GET`	`source:read`
`/agents/{agent}/sources`	`POST`	`source:create`
`/agents/{agent}/sources/{source}/retrain`	`POST`	`source:edit`
`/agents/{agent}/sources/{source}`	`DELETE`	`source:delete`
`/agents/{agent}/training-jobs/{taskId}`	`GET`	`source:read`
`/organizations/{org}/crawls`	`POST`	`source:create`
`/organizations/{org}/crawls/{taskId}`	`GET`	`source:read`

Authorization model

Beyond the key's scopes, every request is checked against the organization:

Owner‑only. API operations require that the key's user is the owner of the target organization. Acting on an organization or agent you do not own returns 403.
Premium gate. Each request re‑verifies the organization's premium/AppSumo entitlement. If it lapses, requests return 403 premium_required even with a valid key.
Expiry. A key's stored expiry is enforced at request time. An expired key returns 401 token_expired. lifetime keys never expire.

Authentication failures

Status	Body `code`	When
`401`	— (`{"message":"Unauthenticated."}`)	Missing, malformed, or revoked key.
`401`	`token_expired`	The key passed its expiry date.
`403`	`premium_required`	Organization is not on a premium/AppSumo plan.
`403`	`insufficient_scope`	The key lacks the scope the endpoint requires.

See Errors for the complete catalogue.