Service accounts and calling agents from an app backend
Creating and rotating service accounts, scopes, token minting, run-as-user vs service account, capacity limits and the backend integration pattern.
Create a service account (Org Console)
- Owner/Tenant admin: Org Console > Manage > Service Accounts (platform admins: Platform Admin > Service Accounts). Create the account; machine role
sa-executor(or the org's executor role). - Account page sections: Agents (Install agent), Permissions, Runs, Usage, Secret & Rotation.
- Create the credential and copy client id + secret (secret shown once) into a local secret file (
novaos_sa_credentials_file), never into chat or git. - Grant scopes/permissions (below) and, for write-classified MCP tools, an exact-tool SA grant.
- Agents > Install agent for the account itself (a personal install does not count). Read back version + Instance ID.
- Test:
novaos_sa_token_test, thennovaos_ask_agent {as: "<ref>", message: {"skill":"ping"}}. Guided:novaos_workflow_start {"workflow":"connect_backend"}.
Scopes for service accounts
- Basic call:
agent:execute agent:read(NOT MCP tools or models). - Models:
llm:model:*(orllm:model:<id>) AND the agent manifest listsllminpermissions.tools. - MCP tools:
mcp:tools:*ormcp:tools:<category>(registered category). - Knowledge:
rag:query rag:collections:read(+rag:parse rag:ingest rag:collections:writeto ingest). - REST connectors:
connector:invoke+connector:<source>:<operation>. Memory:memory:{read,write,delete}:{run,task,agent}(SA tokens cannot call the Memory service directly). - After a role/permission change, mint a NEW token: cached tokens keep old rights. Check
token_response["scope"]contains what you need.
Token
POST {iam}/oidc/token (form)
grant_type=client_credentials client_id=... client_secret=... resource=urn:novaos organization_id=<org> scope=<space separated>
Both resource and organization_id are mandatory (else a silent 403). TTL ~15 min: cache and refresh 60 s early; refresh once on 401. invalid_client = wrong id/secret or expired secret.
Rotation
Secret & Rotation shows Issued at, Expires at, policy and history; Rotate secret. Procedure: rotate -> update the backend secret store -> mint a fresh token -> test one request -> retire the old secret.
Running agents from a backend
POST {gateway}/api/v1/execute{instance_id, input: "<string>", thread_id?, skill?}+X-Idempotency-Key(and bodyidempotency_key). Works with SA tokens on FDE 2.1 (undocumented) and is the only path on fde-us / staging-eu.POST /api/v1/service/runs(skill_idfield, SSE withAccept: text/event-stream) exists only where the gateway hasSA_EXECUTION_ENABLED(404 on fde-us, staging-eu, prod-eu). Prefer execute./a2a/v1/agents/{agent_id}direct A2A: SA only, same restriction.- The gateway derives the run id from idempotency key + thread: re-opening with the same key joins the running run. One key per turn; a new key only after a run NovaOS reports failed.
- Never retry a timeout (the run may still execute; a resend queues a duplicate turn). A 429 or a dispatch failure starts no run: safe to retry.
Details of streaming/recovery: guide
08-runs-streaming. Generated client code:novaos_app_integration_code.
Run as the user vs as the service account
- User-triggered runs: the SPA signs in with Logto (PKCE, org-scoped
urn:novaostoken with agent/mcp/llm/rag scopes), sendsX-NovaOS-User-Tokento your backend on EVERY run-starting request (elseuser_token_missing); the backend resolves/installs the user's own instance (cache per org+user+agent+version; re-resolve once onINSTANCE_NOT_FOUND). - User runs cannot call write-classified MCP tools (-32042): use returned writes (
persistence: "return"). - Background, scheduled and recovery work stays on the SA. Long user runs outlive the user token: keep a renewable grant; never silently fall back to the SA for user-visible actions.
Capacity and limits
- ~8 concurrent service-account runs per org: HTTP 429
CONCURRENCY_LIMIT_EXCEEDED/ConcurrencyLimitError("Maximum concurrent service_account runs (8) reached"). The slot is held while the SSE stream is open. Back off: Retry-After (clamp 1-10 s) else 3 s doubling to 10 s + jitter, 60 s budget, show "Waiting for capacity". - Pod quota: the open returns 200, then a 403 event
exceeded quota: namespace-quota ... pods=150(~1 GiB per pod). Show "The platform is at capacity, try again in a few minutes" (no immediate retry). Consider an app-side run gate (e.g. 15 in flight, 3 per user). - A pod = (user, instance, config) and serves one run at a time; a concurrent run takes a new cold pod (20-45 s; first message ~25 s cold vs ~6 s warm). Idle TTL ~10 min, max ~1 h. Fewer, bigger runs beat many small ones.
- Per-installation limits (install form): timeout, requests/second, requests/minute, concurrency, allowed domains. Tenant rate limits (RPM, TPM, RPD, concurrency) are set by platform admins at Platform Admin > Rate Limits.
Multi-org
Store per org: SA client id + secret REFERENCE (secret manager name, never the secret), instance id. Every component that talks to NovaOS needs the org id configured (else 403 "organization is not served by this deployment").