AIGENCY API access model: The token alone is enough — no scope picker

May 30, 2026 — All new endpoints that shipped with AIGENCY V4.1 (Knowledge Base, Scheduled Tasks, Deep Research, Canvas, Regenerate, Chat Folders) are now reachable through the v2 API. But which token can call which endpoint? This post explains AIGENCY's scope-less access model and why we chose this route.

The call: no scopes

When you create an application, we don't hand you a checkbox form for endpoint permissions. There is no AWS-style fine-grained IAM, no permission matrix similar to Stripe's restricted keys. Instead, the model has two plain layers:

1. Token: From the My API Apps page in your account, you create an app and receive a 32-character token. This token goes into the URL of every v2 API call.
2. Plan: Your account's plan (Pro or Business) determines which features are unlocked. API access is not available on Free and Starter; you cannot create an app there. Pro and Business open all V4.1 features — they differ only in quotas and limits.

A request is verified in this order: token valid → its account's plan supports this feature. If both are green, your request runs.

Operational note: If we need to temporarily disable a capability on AIGENCY's side (e.g. during infrastructure maintenance), the affected endpoint returns 404. This is rare and never implies a permanent change to your account; once resolved, calls with the same token resume.

Why we skipped scopes

Scopes are a fine idea — they limit unauthorized access and make audit logs richer. In practice, though, they introduce three frictions:

• First-touch experience: A developer wants to wire a prototype quickly. Being forced to tick 8 checkboxes leads to "I'm not sure which I need; I'll select them all." Scopes exist in theory; in practice everyone picks "all".
• Maintenance overhead: When we ship a new endpoint, every existing token needs that scope added — otherwise users hit support with "why 403?". A versioning nightmare.
• False sense of security: The real threat is token leakage. Scoped or not, a leaked token lets an attacker read your chats and burn credits. Scopes don't save your credit — they only label "which endpoint burned it".

Instead, we kept three things tight: resource ownership (a token only sees its own account's folders, KBs, chats — other users return 404), rate limit (60 req/min, auto-throttle on abuse), and credit quota (every endpoint returns 402 when the plan is empty).

What this means in practice

An example: from the My API Apps page you click "New Application". We only ask for a name — say, "CRM integration". A token is generated; something like z5PDmoNTQ2t5rQeN9oxw6lmkcRBnP7ub.

What you can do with this token:

• Classic endpoints (newChat, sendMessage, view-chats, resumeChat, deleteChat, credit, ai-team-list) — open regardless of plan.
• V4.1 endpoints — open if your plan is Pro or Business. Free and Starter cannot get a v2 token in the first place, so this state never appears.

So the answer to "can this app reach the Knowledge Base endpoint?" is: yes, if your plan is Pro or higher. No extra permission setting is required.

Where the quotas live

Instead of scopes, real protection sits in quotas. Every feature has a plan-based ceiling:

When a quota fills, the endpoint returns 429 or 403 quota_exceeded and the body states which limit hit. This mechanism is tighter than scopes: scopes flip an endpoint on/off; quotas measure continuously and catch abuse the moment it starts.

If the token leaks

The token rides in the URL, so it can land in browser history, proxy logs, error reports. So never put the token on the client side (frontend, mobile app, GitHub repo). Keep it server-side only.

If you suspect a leak — even without proof — go to My API Apps, delete the old token and create a new app. The old token is revoked immediately; any leaked copies stop working at once. This is faster than tweaking a scope list.

What a call looks like

A classic flow: check credit → pick an assistant → start a new chat → send a message. With cURL:

# Check credit (free; no counter)
curl https://aigency.dev/api/v2/credit/YOUR_API_TOKEN

# New chat (assistant id=16: Alparslan)
curl -X POST https://aigency.dev/api/v2/newChat/16/YOUR_API_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

# Knowledge Base — V4.1, open if plan is Pro/Business
curl https://aigency.dev/api/v2/knowledge-base/YOUR_API_TOKEN

Would the third call have failed without a scope setting? No. There are no scopes. Token + plan green means your request runs.

Roadmap: webhooks and finer quotas

Webhook infrastructure is on the v3 roadmap — when a task completes, a deep research finishes, or credit falls below a threshold, we'll POST to your application over HTTPS. That removes the need for polling.

Will our stance on scopes change? Maybe. If multi-user scenarios (e.g. different teams sharing one company account and needing per-endpoint restrictions) become a frequent ask, a scoped token model could be added. For now the demand isn't there — what we observe is that anyone holding an API token wants to try every feature their plan supports.

For the full endpoint list, code samples and OpenAPI/Postman files, see the API tab on /docs.