Fichas API personales

Los tokens API personales permiten que un usuario de CMS que haya iniciado sesión delegue el trabajo en una herramienta de operador o de inteligencia artificial sin compartir una contraseña ni otorgar autoridad para toda la instalación. La IA actúa como ese usuario: cada solicitud está limitada por la configuración del token y el acceso actual al CMS del usuario.

Tokens personales y de sistema

Tipo de token Creado a partir de Propietario previsto autoridad
Ficha API personal Perfil → Tokens API personales Editor, Site admin o Super admin El contenido y el sitio funcionan dentro de la función activa del propietario y los sitios seleccionados
Token API del sistema Sistema → Tokens API Super admin Automatización confiable a nivel de instalación con capacidades seleccionadas explícitamente

Los tokens personales excluyen deliberadamente las actualizaciones del sistema a nivel de instalación, las copias de seguridad, el mantenimiento, los complementos, las aplicaciones integradas, los dominios, los activos físicos del sitio/página y la representación administrativa. Un superadministrador que necesite automatizar esas operaciones debe crear un token de API del sistema independiente. Esto evita que un asistente personal se convierta silenciosamente en un operador de instalación.

Regla de permiso efectiva

Un token personal puede realizar una operación solo cuando se pasan todas estas comprobaciones:

  1. El token está activo y no ha caducado.
  2. Su propietario sigue siendo un usuario activo del CMS.
  3. La capacidad solicitada se selecciona en el token.
  4. El rol actual del propietario aún permite esa capacidad.
  5. El sitio de destino se selecciona en el token y permanece accesible para el propietario.
  6. El estado actual del flujo de trabajo de la página permite al propietario realizar el cambio solicitado.
  7. La solicitud proviene de una red permitida, cuando se configura una lista de direcciones IP permitidas.
  8. No se han excedido los límites de solicitud específicos del token y de toda la instalación.

Cambiar la función de un usuario, las asignaciones de sitio o el estado activo entra en vigor en la siguiente solicitud de API. Una ficha nunca conserva la autoridad que su propietario ha perdido.

Matriz de funciones

Área Ficha del editor Ficha Site admin Ficha personal Super admin token del sistema
Leer contenido del sitio asignado Sí Sí Todos los sitios Si se concede
Crear y cambiar contenido borrador Sí Sí Todos los sitios Si se concede
Publicar o archivar No Si se concede Si se concede Si se concede
Configuración de presentación de sitio seguro No Si se concede Si se concede Si se concede
Navegación, Shared Slots, medios y participación Dentro de los sitios seleccionados y asignados, si se concede Dentro de los sitios seleccionados y asignados, si se concede Dentro de los sitios seleccionados, si se concede Si se concede
Usuarios, actualizaciones, copias de seguridad, mantenimiento, complementos, aplicaciones, dominios, activos físicos No No No Sólo con la capacidad correspondiente

El formulario de token muestra solo capacidades que el usuario actual puede delegar. Seleccionar una capacidad es un límite superior, no una forma de eludir el rol.

Crear un token

  1. Obra Profile y seleccione Administrar tokens API.
  2. Ingrese un nombre que identifique al cliente o trabajo.
  3. Seleccione los sitios a los que puede llegar la IA.
  4. Seleccione solo las capacidades que necesita el trabajo.
  5. Elija un período de vencimiento.
  6. Establezca el límite de solicitudes al lado del control de vencimiento, debajo de la selección de sitio permitido. Opcionalmente, configure una lista de IP permitidas en controles de red.
  7. Seleccionar Crear token.
  8. Copie el token inmediatamente. Su valor simple se muestra solo una vez.

El panel de éxito proporciona la URL base de la API, un ejemplo de variable de entorno y un mensaje de configuración de IA listo para copiar. Entregue el secreto únicamente a la herramienta prevista y guárdelo en el almacén secreto de esa herramienta.

Editar, revisar, revocar o eliminar

  • Edit cambia el nombre, los sitios seleccionados, las capacidades, la renovación del vencimiento, la lista de direcciones IP permitidas y el límite de solicitudes sin revelar ni reemplazar el secreto.
  • Actividad muestra las últimas diez solicitudes: resultado, hora, método, ruta sin cadena de consulta, ruta, capacidad requerida, IP y un agente de usuario abreviado.
  • Revoke evita inmediatamente una mayor autenticación mientras conserva el token y el historial de actividad.
  • Delete elimina permanentemente el token y su historial de actividad.

Los cuerpos de solicitud y respuesta, las cadenas de consulta, los valores de portador, los hashes de tokens y las vistas previas de tokens nunca se almacenan en las filas de actividad.

Controles de red

La lista de permitidos acepta una dirección IPv4/IPv6 exacta o una red CIDR por línea, por ejemplo:

203.0.113.10
198.51.100.0/24
2001:db8::/32

Deje la lista vacía para permitir cualquier red. Elija un límite específico de token de 30, 60, 120 o 300 solicitudes por minuto. Los tokens existentes sin un límite máximo de almacenamiento utilizan 60 solicitudes por minuto. La limitación API en toda la instalación aún se aplica, por lo que el límite efectivo es el límite más bajo aplicable.

Proxies inversos y CDN

Las comprobaciones de red utilizan la IP del cliente resuelta por Laravel. Cuando el host está detrás de un equilibrador de carga, un proxy inverso o una CDN, configure el manejo del proxy confiable de Laravel para las direcciones de proxy reales y los encabezados reenviados. Verifique la dirección resuelta antes de habilitar una lista de permitidos restrictiva. No confíe en los encabezados reenviados por clientes de Internet arbitrarios; de lo contrario, la persona que llama puede falsificar la dirección utilizada por la política.

Conectar una IA

Configure los valores generados en el almacén secreto confiable de la herramienta:

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

La herramienta debe llamar primero a GET /webadmin/api. El descubrimiento autenticado devuelve sus capacidades, política de red personal, OpenAPI y enlaces de guía, y los próximos pasos recomendados. Debe validar los planes de contenido antes de aplicarlos y solicitar la aprobación explícita del usuario antes de realizar operaciones de publicación o destructivas.

Contrato de error

HTTP Código Significado
401 invalid_internal_api_token El token falta, no es válido, está revocado, ha caducado o ya no está respaldado por un usuario activo de CMS
403 missing_internal_api_capability El token actualmente no tiene la capacidad requerida
403 delegated_site_access_denied El recurso seleccionado o el sitio enviado está fuera del alcance activo del propietario del token
403 delegated_workflow_access_denied El propietario no puede editar la página en su estado de flujo de trabajo actual
403 delegated_operation_denied La operación es a nivel de instalación y no puede utilizar un token personal.
403 delegated_network_access_denied La IP del cliente resuelta está fuera de la lista de tokens permitidos
429 personal_api_token_rate_limit_exceeded Se alcanzó el límite máximo de solicitudes específicas de tokens; honor Retry-After
422 Código de validación específico del terminal La solicitud está autenticada pero su carga útil o transición de estado no es válida

Todos los errores de API son JSON e incluyen enlaces de descubrimiento seguros para el público cuando estén disponibles.

  • Crear un token por IA, integración o trabajo limitado.
  • Déle la menor cantidad de sitios y capacidades que necesita.
  • Prefiere períodos de vencimiento cortos y renueva deliberadamente.
  • Utilice una lista de IP permitidas de salida estable cuando la plataforma de IA proporcione una.
  • Revisar la actividad reciente después de la configuración inicial y después de un trabajo delicado.
  • Revocar inmediatamente si un secreto puede haber sido expuesto.
  • Nunca pegue tokens en tickets, registros, capturas de pantalla, control de fuente o avisos que puedan ser retenidos por servicios no relacionados.

Consulte Internal Content API, Users And Permissions y Security para conocer la API subyacente, la función y los límites de implementación.