Documentation

API and OAuth overview

AnnexGroup exposes a REST API under /api/v1/. Authentication Session cookie: for requests from the web UI OAuth 2.0: for third-party applications API tokens / a…

AnnexGroup exposes a REST API under /api/v1/.

Authentication

• Session cookie: for requests from the web UI
• OAuth 2.0: for third-party applications
• API tokens / access tokens: for scripts, external systems and AI agents

Managing access tokens

Personal tokens are created under Settings → Access tokens. Administrators can additionally issue server admin tokens with fine-grained scopes under Administration → Admin access tokens.

Available admin scopes:

• admin – full admin access
• admin:read – read access to the admin API
• admin:write – write access to the admin API
• admin:users, admin:agents, admin:domains, admin:queue, admin:security, admin:license, admin:backup, admin:settings, admin:mail

Access tokens are particularly suited to:

• Automation scripts (backup, monitoring, reporting)
• External administration through the REST API
• AI agents that are permitted to read or adjust server configuration

Admin access token API

Creating a token:

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"Monitoring agent","scopes":["admin:read","admin:queue"],"expires_in_days":90}' \
     https://annexgroup.example/api/v1/admin/tokens

The response carries the plaintext token exactly once:

{"token":"ag_...","expires_at":"2026-10-28T12:00:00Z"}

Admin API

Every administrative function is reachable over the REST API as well:

Registering OAuth apps

Users can register applications under Settings → OAuth apps:

1. Give the app a name and a redirect URI
2. Receive the client ID and client secret
3. Grant scopes according to the principle of least privilege

Frequently used endpoints

The OpenAPI specifications live at:

• AnnexTalk wire protocol: docs/talk-protocol/v1/openapi.yaml
• Admin API: docs/openapi-admin.yaml

Example integrations

Under examples/api-admin/ you will find:

• annexgroup_admin.py — a declarative Python tool for users, domains, aliases and DKIM
• config.yaml — an example configuration
• ansible/playbook.yml — an idempotent Ansible playbook

These make a good starting point for infrastructure-as-code workflows.