Skip to main content

Service accounts

Use a service account when a tool or script, rather than a person, needs to call AION, for example an n8n workflow or a nightly report job. This page is for administrators who create these accounts and their API keys, and for integrators who use the keys.

A service account is a non-human identity for an integration (n8n, a nightly script, another backend). It uses AION only through API keys. Unlike a personal key, which acts as a person, a service-account key has:

  • its own identity (svc-<slug>);
  • its own conversations;
  • its own profile restrictions.

The integration keeps working when an employee leaves, and its traffic never shows up in anyone's chat-ui.

Only administrators create and manage service accounts and their keys, from admin-ui → Service accounts or /admin/service-accounts.

Model​

A service account is a regular users row with account_type='service'. Because conversations, profile access, memory, MCP credentials and SQL project membership are all keyed on users.id / users.identifier, every one of them works unchanged.

FieldMeaning
identifiersvc-<slug>; slug ^[a-z0-9][a-z0-9._-]{1,60}$. The svc- prefix is reserved: POST /admin/users rejects it with 422 identifier_reserved.
account_typeservice (people are human).
disabled_atSet while the account is disabled. Keys are kept but rejected with 401 api_key_owner_disabled.
metadata.service{description, ltm_enabled, created_by}.
max_api_keys / api_key_max_ttl_daysKey quota (1–100) and maximum lifetime (1–365 days).

Migration g5b6c7d035 adds account_type and disabled_at. On SQLite the startup schema patch adds them too.

What a service account cannot do​

PathBehaviour
Password login (/auth/login)Always refused, even if a password hash were written by hand.
Chat token (Bearer from /auth/login)403 service_account_token_not_allowed.
SSO loginAn SSO identity is never linked to a service account.
Password links / temp passwords / forgot password / recover CLIRefused (409 service_account_no_password) or skipped silently.
SSO migrationAlways exempt; it does not count in the migration progress.
/admin/*Refused: API keys never reach the admin router, so there is no admin scope.
/v1/me/* (API keys, memory, WhatsApp, Telegram, MCP integrations)Refused: those endpoints need a chat token.
People endpoints (PUT /admin/users/{id})409 service_account_use_dedicated_endpoint.

The available scopes are the user scopes (chat, conversations:read|write, files:read|write), with the same endpoint map as personal keys.

Admin API (/admin/service-accounts)​

Requires an admin chat token. Every mutating call writes audit_log:

  • service_account.create|update|disable|enable|delete;
  • service_account.key.create|revoke.

The payload never contains a secret (only key id, prefix, scopes and expiry).

EndpointPurpose
GET /admin/service-accounts{items: [{id, identifier, display_name, description, disabled, disabled_at, ltm_enabled, max_api_keys, api_key_max_ttl_days, active_keys, last_used_at, created_at, created_by, profiles}]}
POST /admin/service-accounts {slug, display_name?, description?, ltm_enabled=false, max_api_keys=5, api_key_max_ttl_days=90}201. Errors: 422 invalid_service_slug, 409 user_exists. Allowed in SSO mode too.
PATCH /admin/service-accounts/{id}Any of display_name, description, disabled, ltm_enabled, max_api_keys, api_key_max_ttl_days.
DELETE /admin/service-accounts/{id}Deletes the account, its keys and profile access. Conversations are kept, as for people.
GET /admin/service-accounts/{id}/keys{policy, keys} (same shape as /v1/me/api-keys).
POST /admin/service-accounts/{id}/keys {name, scopes, expires_in_days}201 with the key object plus key, shown once. Same errors as personal keys.
DELETE /admin/service-accounts/{id}/keys/{key_id}Soft revoke.

Profile restrictions use the existing GET/POST /admin/users/{id}/profiles with the service account's id.

GET /admin/users hides service accounts. Pickers that must offer them pass ?include_service=1, and each row then carries account_type.

Long-term memory​

LTM is off by default for service accounts: automation traffic would otherwise flood the memory with low-value notes. While it is off, both extraction (extract_and_persist, pre-compaction flush included) and retrieval (wake_up) are skipped.

Enable it per account with PATCH {"ltm_enabled": true}. The flag is cached for about 30 seconds per process and the PATCH invalidates the cache. People are never affected, and the global AION_LTM_* switches still apply on top.

Usage​

# Admin: create the account and a 30-day chat key
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"slug":"n8n-reports","description":"Weekly KPI report"}' \
https://aion.example.com/api/admin/service-accounts
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"n8n prod","scopes":["chat"],"expires_in_days":30}' \
https://aion.example.com/api/admin/service-accounts/$ID/keys

# Integration: call the agent as svc-n8n-reports
curl -H "X-Api-Key: $AION_KEY" -H 'Content-Type: application/json' \
-d '{"message":"Summarise last week KPIs"}' https://aion.example.com/api/v1/chat

The OpenAI-compatible POST /v1/chat/completions accepts the same key.

Key rotation​

Keys always expire, after at most api_key_max_ttl_days (365 at most). To rotate a key:

  1. Create the new key while the old one is still valid; the quota must leave room for both.
  2. Deploy the new key to the integration.
  3. Revoke the old key.

last_used_at on each key shows whether the old key is still in use.

Verification​

src/test/test_service_accounts.py covers:

  • creation and key use as svc-*;
  • validation, quota and TTL;
  • disable, enable and revoke;
  • login and chat-token lockout;
  • /admin/* refusal for service keys;
  • the /admin/users separation and creation in SSO mode;
  • profile restrictions, deletion and LTM gating.