API Server

Hosting the API

The API is served by the same application as the interface. There is no separate API process to deploy, configure or keep in step.

Where to find it

Architect Panel → Integration & Connections:

• API Server — the settings and the request log
• Deployments — how the application is deployed

Architect Panel → Configuration:

• Site Settings — rate limiting and request logging

Why that is the right arrangement

A separate API service would need its own copy of the permission model, the field security rules and the audit machinery — and any drift between the two would be a security bug rather than an inconvenience. Serving both from one application means a permission change applies to both at once because there is only one of them.

Scaling it

Scaling the API is scaling the application: more capacity serves both. Where API traffic is heavy enough to want isolating from interactive users, that is a web server and infrastructure arrangement — routing the API path to its own pool of workers — rather than a platform setting.

Treat it as an infrastructure decision and take it with whoever runs your hosting. There is nothing to switch on here.

Two health endpoints, and they answer different questions

• Liveness — returns success as long as the web server is serving requests at all. No database, no session, no application bootstrap.
• Readiness — also checks the primary database is reachable, and fails if it is not.

Point them at the right things

This distinction is the one that catches people out. Use liveness for your load balancer's health check, and readiness for monitoring.

If the load balancer checks the database, a brief database blip takes every application instance out of service simultaneously — turning a short, recoverable problem into a total outage. The liveness check is deliberately cheap and deliberately ignorant of the database for exactly that reason.

The health endpoints are not authenticated

Necessarily — a load balancer cannot hold a credential. They are built to be safe unauthenticated: they do not load the application, do not touch sessions, and never emit connection details in a response.

Logging and retention

Requests are logged by default, with a retention period in days. There is also a switch for whether successful requests are recorded or only failures.

Leave successes on. With them off the log stays small and still answers "why did this integration break" — but it loses "is this key still in use" and every usage statistic. As the setting itself puts it, the honest reading of an empty log should be "nothing happened", not "nothing was written down".

Check the log after any deployment

Integrations fail quietly. They retry, they log at their end, and often nobody tells you for days. A look at the request log for new failure patterns after a release is the cheapest way to find out first.

Worked example

An installation runs behind a load balancer checking the liveness endpoint every ten seconds, with monitoring polling readiness every minute. A database failover takes forty seconds: monitoring alerts, the load balancer keeps every instance in service, and the API returns errors briefly instead of the whole site becoming unreachable.

Recommendations

• Liveness for the load balancer, readiness for monitoring. Never the other way round.
• Keep successful-request logging on.
• Set retention deliberately — the log grows with traffic.
• Review the log after every deployment.

Authentication Modes

Ordinary API callers use an API key. The AI tool and agent interfaces can additionally accept OAuth, and choosing between them is a real decision.

Where to find it

Architect Panel → Integration & Connections:

• AI Tool Access (MCP) — the AI tool interface and its settings
• Agent Access (A2A) — the agent interface and its settings
• API Server — API keys and their capability flags
• OAuth Tokens — tokens issued to interactive clients

The two modes

• OAuth — a person signs in and consents, and the client receives a token that acts for them. The right model when there is a human at a keyboard.
• API key — a long-lived credential acting as a fixed identity. The right model when there is nobody to consent.

When a key is the correct choice

A scheduled script, a self-hosted agent, a background process. These have no user to prompt, so an interactive consent flow is not merely inconvenient — there is no one to complete it.

Each interface has its own switch for whether keys are accepted, and both ship enabled. Turning one off restricts that interface to interactive clients only, which is the stricter posture where all your legitimate use is human-driven.

A key's access is on the key

When a key is used, the access level is the one set on the key — its identity's permissions, plus whichever of the three capability flags it carries. There is no consent step to narrow it further, which is the trade for not needing a person.

So a key permitted for AI tool access should be an identity scoped to exactly what that tool needs. The temptation to reuse an existing broad key is the mistake here.

Grant the capability flags deliberately

The MCP and A2A flags are separate from data permissions and ship off. A key that carries one can reach an entire subsystem, so adding a flag is a decision about surface area rather than about data.

Do not enable them on a key created for an ordinary integration on the grounds that it might be useful later.

Prefer OAuth where there is a person

Because the token is attributable to them, expires, and can be revoked without disturbing anything else. A shared key used by several people is the worst of both worlds — the audit trail records the key rather than the person, and revoking it affects everybody.

Review what holds these capabilities

Periodically list the keys carrying MCP or A2A flags. It should be a short list you can account for, and it is the list an attacker would most like to be on.

Keys still expire

Everything in the API keys article applies: name them, expire them, watch last-used, and rotate by overlapping. A long-lived credential for an automated agent is exactly the kind that gets forgotten.

Worked example

An organisation uses OAuth for its staff's AI tooling, so each person's activity is attributable and revocable. One self-hosted agent runs on a schedule with no user, so it gets a key — its own identity, read-only on two datastores, with the AI tool flag and nothing else, expiring annually. The list of flag-carrying keys is one entry long.

Recommendations

• OAuth where there is a person, keys where there is not.
• A dedicated narrow identity for every key carrying a capability flag.
• Never add a flag speculatively.
• Review flag-carrying keys as a short, accountable list.