Referencia de API

La API de Auris es una API REST que proporciona acceso programático a toda la funcionalidad IAM: autenticación, gestión de usuarios, roles, permisos, organizaciones, autorización de grano fino y más. Todas las respuestas de la API usan JSON.

URL Base

https://api.altovar.net/api

Reemplaza api.altovar.net con el dominio donde está desplegada tu instancia de Auris. Si estás usando el servicio cloud de Auris, tu dominio es el que se muestra en la Consola en Configuración → Dominios Personalizados.

Autenticación

Token Bearer

La mayoría de los endpoints requieren un token de acceso válido en la cabecera Authorization:

Authorization: Bearer <access_token>

Los tokens de acceso son JWTs de corta duración (predeterminado 15 minutos) obtenidos a través de los endpoints de autenticación. Están firmados con RS256 (o HS256 según la configuración) y pueden verificarse localmente usando el endpoint JWKS.

Nivel de Acceso por Tipo de Endpoint

Cabecera de Tenant

Auris es una plataforma multi-tenant. Las solicitudes a endpoints de administración deben incluir el identificador del tenant:

x-tenant: <tenant-id>

El ID de tenant es el nombre del realm configurado en tu despliegue de Auris. Para la instalación predeterminada, es default. Para configuraciones de tenant personalizadas, es el nombre del realm que se muestra en la Consola en Configuración → General.

Si se omite la cabecera en endpoints que la requieren, la API devuelve 400 Bad Request con el código MISSING_TENANT.

Formato de Solicitud

Usa Content-Type: application/json para todas las solicitudes POST, PUT y PATCH con cuerpo de solicitud:

Content-Type: application/json

Ejemplo de solicitud:

curl -X POST https://api.altovar.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "secreto"}'

Para cargas de archivos (importación de usuarios), usa multipart/form-data.

Formato de Respuesta

Todas las respuestas de la API siguen un formato de sobre consistente.

Respuesta Exitosa

{
  "ok": true,
  "data": { }
}

El campo data contiene el resultado. Su forma varía según el endpoint y se documenta individualmente para cada uno.

Respuesta de Error

{
  "ok": false,
  "error": {
    "code": "CÓDIGO_DE_ERROR",
    "message": "Descripción legible de lo que salió mal."
  }
}

Códigos de Estado HTTP

Códigos de Error Comunes

Paginación

Los endpoints de lista devuelven resultados paginados usando números de página basados en cursor.

Forma de la Respuesta

{
  "ok": true,
  "data": {
    "data": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Parámetros de Consulta

Ejemplo:

GET /api/users?page=2&limit=50

Limitación de Velocidad

Cada respuesta incluye cabeceras de limitación de velocidad:

Cuando se supera un límite de velocidad, la API devuelve 429 Too Many Requests con una cabecera Retry-After que indica cuántos segundos esperar antes de reintentar.

Niveles de Limitación de Velocidad

CORS

El Intercambio de Recursos de Origen Cruzado (CORS) se aplica en todos los endpoints de la API. Los orígenes permitidos deben registrarse en la configuración de la Aplicación en la Consola de Auris en Aplicaciones → [App] → Orígenes Permitidos.

Las solicitudes de verificación previa OPTIONS se manejan automáticamente. Se permiten credenciales (cookies) cuando el origen de la solicitud está registrado.

Para registrar un origen:

1. Ve a Consola → Aplicaciones
2. Selecciona tu aplicación
3. Añade el origen a Orígenes Permitidos (por ejemplo, https://app.tudominio.com)

Descubrimiento OIDC

Auris expone un documento de Descubrimiento OpenID Connect estándar:

GET /.well-known/openid-configuration

Esto devuelve un documento JSON que contiene todas las URLs de endpoint, tipos de concesión admitidos, ámbitos, algoritmos de firma y otros metadatos. Las bibliotecas OIDC estándar usan esto para auto-configurarse.

Campos de ejemplo de la respuesta:

{
  "issuer": "https://api.altovar.net",
  "authorization_endpoint": "https://api.altovar.net/api/oauth/authorize",
  "token_endpoint": "https://api.altovar.net/api/auth/token",
  "userinfo_endpoint": "https://api.altovar.net/api/auth/validate",
  "jwks_uri": "https://api.altovar.net/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "HS256"],
  "scopes_supported": ["openid", "profile", "email"]
}

JWKS

Las claves de firma públicas usadas para la verificación de JWT están disponibles en:

GET /.well-known/jwks.json

Respuesta:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Los clientes almacenan en caché las claves durante hasta 1 hora (Cache-Control: public, max-age=3600). La rotación de claves añade una nueva clave al conjunto; las claves antiguas permanecen presentes hasta que expiran los tokens emitidos con ellas.

Clientes SDK

En lugar de llamar a la API directamente, considera usar un SDK de Auris que gestiona automáticamente los tokens, PKCE, actualización y manejo de errores:

Consulta la documentación de SDKs para guías de instalación y uso.