ES

Documentación

Resumen de la API y OAuth

AnnexGroup proporciona una API REST en /api/v1/.

Autenticación

  • Cookie de sesión: Para solicitudes de la interfaz web
  • OAuth 2.0: Para aplicaciones de terceros
  • Token de API / Access Tokens: Para scripts, sistemas externos y agentes de IA

Gestión de Access Tokens

En Configuración → Tokens de acceso se pueden crear tokens personales. Los administradores pueden además emitir en Administración → Tokens de acceso de administrador tokens de administrador del servidor con ámbitos (permisos) muy específicos.

Ámbitos de administrador posibles:

  • admin – Acceso completo de administrador
  • admin:read – API de administración de solo lectura
  • admin:write – API de administración de escritura
  • admin:users, admin:agents, admin:domains, admin:queue, admin:security, admin:license, admin:backup, admin:settings, admin:mail

Los Access Tokens son especialmente adecuados para:

  • Scripts de automatización (copias de seguridad, supervisión, informes)
  • Administración externa a través de la API REST
  • Agentes de IA que pueden leer o ajustar configuraciones del servidor

API de Access Tokens de administrador

Método Endpoint Descripción
GET /api/v1/admin/tokens Listar los tokens de administrador propios
POST /api/v1/admin/tokens Crear un nuevo token de administrador
DELETE /api/v1/admin/tokens/{id} Revocar un token de administrador

Ejemplo de creación de un 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

La respuesta contiene el token en texto claro una sola vez:

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

API de administración

Todas las funciones administrativas también están disponibles a través de la API REST:

Método Endpoint Descripción
GET /api/v1/admin/users Listar usuarios
POST /api/v1/admin/domains Crear un dominio
GET /api/v1/admin/queue Mostrar la cola de correo
POST /api/v1/admin/security/preset Aplicar un perfil de seguridad

Registrar aplicaciones OAuth

En Configuración → Aplicaciones OAuth los usuarios pueden registrar aplicaciones:

  1. Indicar el nombre de la aplicación y la URI de redirección
  2. Recibir el Client-ID y el Client-Secret
  3. Asignar los ámbitos según el principio de mínimo privilegio

Puntos finales importantes

Método Endpoint Descripción
GET /api/v1/mailboxes Listar buzones
GET /api/v1/messages Obtener correos
POST /api/v1/messages Enviar correo
GET /api/v1/contacts Listar contactos
GET /api/v1/events Obtener citas

Las especificaciones OpenAPI se encuentran en:

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

Integraciones de ejemplo

En examples/api-admin/ encontrará:

  • annexgroup_admin.py — Herramienta declarativa en Python para usuarios, dominios, alias y DKIM
  • config.yaml — Configuración de ejemplo
  • ansible/playbook.yml — Playbook de Ansible idempotente

Estos ejemplos sirven como punto de partida para flujos de trabajo de Infrastructure as Code.

¿Algo poco claro o mal descrito? Díganoslo — lo corregiremos. Su pregunta nos muestra dónde flojea el texto.