Saltar al contenido principal

Ámbitos de administración de claves API

Para automatizar tareas que /api/v1 no cubre (usuarios, ajustes, exportaciones…), una clave puede llamar a los servicios del panel (/api/services/app/{Servicio}/{Método}, la misma API que usa la interfaz) con ámbitos de administración. La clave actúa como una cuenta de servicio de tu cuenta, limitada por esos ámbitos.

Fuera del contrato estable

Estas rutas siguen la API del panel y pueden cambiar con él; no forman parte de /api/v1. Usa una cuenta de servicio con solo los roles que la integración necesita.

Ámbitos​

ÁmbitoPermite
admin:*Todo lo que la cuenta de servicio pueda hacer
admin:<permiso>Solo ese permiso y los que cuelgan de él, por ejemplo admin:Pages.Administration.Users cubre Pages.Administration.Users.Create

Los permisos efectivos son los de la cuenta de servicio ∩ los ámbitos de la clave. Una clave sin ámbito de administración recibe 403 en /api/services/app/*, y los ámbitos de administración nunca los da una clave antigua sin ámbitos.

Configurarlo​

Hoy se hace por API, no desde el formulario de claves. Necesitas el permiso Conceder scopes de administración por API (Pages.Administration.ApiKeys.AdminScopes), con una sesión de administrador.

  1. Crea la cuenta de servicio: POST /api/services/app/ApiKey/CreateServiceAccount con name. Es un usuario sin acceso interactivo: nunca inicia sesión (contraseña, acceso externo, impersonación y demás están rechazados).
  2. Dale permisos como a cualquier usuario (roles o permisos) en la gestión de usuarios.
  3. Crea o edita la clave con CreateApiKey o UpdateApiKey indicando scopes (por ejemplo "admin:Pages.Administration.Users") y serviceUserId con el id de la cuenta de servicio.
curl -s "$BASE/api/services/app/User/GetUsers?MaxResultCount=10" \
  -H "Authorization: Bearer mk_xxxxxxxx"

Reglas de seguridad​

  • Una clave con ámbito de administración necesita una cuenta de servicio activa de la misma cuenta; no se puede ligar un usuario normal.
  • No puedes conceder un admin:<permiso> que tú no tengas, ni ligar una cuenta de servicio que, dentro de los ámbitos de la clave, tenga un permiso que tú no tengas (ligar al administrador con admin:* exige tener todos sus permisos).
  • Una llamada hecha con la clave no puede modificar su propia cuenta de servicio (permisos, roles, correo, contraseña, borrado): 403.
  • Tampoco puede dar permisos o roles que el propio llamante no tenga, ni cambiar el correo o la contraseña de un usuario con más permisos.
  • Solo se alcanzan acciones que exigen un permiso concreto. Los servicios de uso personal (perfil, cuenta, cuentas vinculadas, delegaciones…) dan siempre 403 con una clave, incluso con admin:*.
  • Cada llamada queda en un registro de auditoría (clave, cuenta de servicio, ruta, permisos concedidos o denegados y estado).

También puedes obtener un token de corta duración con OAuth2 y pedirle admin:* o un admin:<permiso>; el token queda acotado igual.

Relacionado​