> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Descripción general de la API > API con clave de servicio para análisis de ACU, gestión de grupos y límites de ACU en despliegues federales. Esta documentación es para los despliegues federales de Devin. [Volver a la documentación de Devin](/es/get-started/devin-intro) Los administradores federales de Enterprise pueden consultar mediante programación el consumo de ACU y gestionar los [grupos](/es/federal/groups), la [disponibilidad de modelos](/es/federal/model-provisioning) y los [límites de ACU](/es/federal/acu-limits) mediante una API con clave de servicio. Un [SDK de Python](/es/federal/api/python-sdk) encapsula cada endpoint descrito en esta sección. Los endpoints de gestión de grupos y de límite de ACU solo están disponibles en despliegues federales autohospedados y multi-tenant. No están disponibles en despliegues comerciales. Los endpoints de análisis (`/Analytics`, `/UserPageAnalytics` y `/CascadeAnalytics`) también verifican el nivel de acceso a análisis del despliegue; un equipo sin acceso a análisis recibe `permission_denied`. ***
## URL base
Todas las solicitudes son de tipo JSON `POST` al servidor de API de tu despliegue: ``` https:///api/v1/ ``` Reemplaza `` por el dominio de la API de tu despliegue federal.
## Autenticación
Cada solicitud se autentica mediante una **clave de servicio** incluida en el cuerpo de la solicitud: ```json theme={null} { "service_key": "your_service_key_here" } ``` Para crear una clave de servicio, inicia sesión en el portal federal como administrador del equipo y ve a **Settings → Claves de servicio**. Luego, crea una clave con los permisos necesarios para los endpoints que planeas invocar. Mantén seguras las claves de servicio. Nunca las expongas en código del lado del cliente ni las confirmes en repositorios.
### Permisos necesarios
| Endpoint | Permiso necesario | | ------------------------------------------------------------------------------------------------------------------------ | ----------------- | | [Informe de uso heredado](/es/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` y `/CascadeAnalytics`) | Teams Read-Only | | [Consumo de ACU](/es/federal/api/acu-consumption) (`/Analytics`) | Analytics Read | | [Listar grupos](/es/federal/api/group-management#list-groups) (`/ListGroups`) | Teams Read-Only | | [Obtener un grupo](/es/federal/api/group-management#get-group) (`/GetGroup`) | Teams Read-Only | | [Crear un grupo](/es/federal/api/group-management#create-group) (`/CreateGroup`) | Teams Update | | [Actualizar un grupo](/es/federal/api/group-management#update-group) (`/UpdateGroup`) | Teams Update | | [Eliminar un grupo](/es/federal/api/group-management#delete-group) (`/DeleteGroup`) | Teams Update | | [Listar miembros de un grupo](/es/federal/api/group-management#list-group-members) (`/ListGroupMembers`) | Teams Read-Only | | [Agregar miembros a un grupo](/es/federal/api/group-management#add-group-members) (`/AddGroupMembers`) | Teams Update | | [Eliminar miembros de un grupo](/es/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`) | Teams Update | | [Obtener el límite de ACU de un usuario](/es/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`) | Teams Read-Only | | [Actualizar el límite de ACU de un usuario](/es/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`) | Teams Update |
### Claves con ámbito de equipo y de grupo
Las claves de servicio se limitan a un ámbito al crearse: * Las **claves con ámbito de equipo** pueden consultar datos de todo el equipo y gestionar todos los grupos del equipo. * Las **claves con ámbito de grupo** están limitadas al grupo asignado. Pueden leer el total acumulado de ACU y las filas de usuarios del grupo, listar y leer únicamente ese grupo, y leer o actualizar los límites de ACU solo para los miembros actuales de ese grupo. No pueden leer los totales ni las filas de usuarios de todo el equipo, ver otros grupos ni crear grupos. Las listas de grupos, miembros de grupos y filas de ACU por usuario están paginadas: * `page_size` — opcional; el valor predeterminado es 100 y el máximo es 1000. Si se omite o se pasa `0`, se usa el valor predeterminado. * `next_page_token` — se devuelve cuando hay más resultados. Vuelva a pasarlo como `page_token` en una solicitud idéntica en todos los demás aspectos (incluido el mismo `page_size`) para obtener la página siguiente. Los tokens de página son opacos y están cifrados. Caducan después de 24 horas. Los tokens de consumo de ACU están vinculados al endpoint, el equipo, el ámbito, el período, la selección de grupos y el tamaño de página. Los tokens de las listas de grupos y miembros están vinculados al endpoint, el equipo, el ámbito y el tamaño de página. Cambiar un valor vinculado entre páginas devuelve un error `invalid_argument`.
## Errores
Los errores se devuelven en formato JSON con un código y un mensaje: ```json theme={null} { "code": "permission_denied", "message": "service key role is missing the required permission" } ``` | Código | Significado | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unauthenticated` | Falta la clave de servicio, no es válida o ha caducado. | | `permission_denied` | El rol de la clave de servicio no cuenta con el permiso requerido. | | `invalid_argument` | La solicitud está mal formada; por ejemplo, el período no es válido, se mezclan consultas de analíticas tipadas y personalizadas, la actualización está vacía o el token de página está obsoleto o no coincide. | | `not_found` | El recurso no existe, pertenece a otro equipo o está fuera del ámbito de la clave de servicio. No se puede distinguir entre recursos de otros equipos, fuera del ámbito y recursos inexistentes. | | `failed_precondition` | La solicitud es válida, pero no se puede completar en el estado actual; por ejemplo, al establecer un límite de ACU para un equipo que no usa facturación por ACU o al seleccionar una dirección de correo electrónico de usuario ambigua. | | `already_exists` | El nombre de grupo solicitado ya está en uso por el equipo. | | `internal` | El servicio no pudo completar la solicitud. |