Autenticación y scopes¶
La API pública acepta una credencial asociada al espacio. En una integración de servidor puedes enviarla como bearer token o como cabecera de API key:
Como alternativa:
Usa HTTPS siempre. No envíes credenciales en query strings ni desde código JavaScript que se entregue al navegador.
Scopes¶
Los scopes limitan lo que una clave puede leer o modificar. Según la capacidad contratada pueden existir permisos para:
- clientes;
- prospectos;
- tareas;
- calendario;
- notas;
- formularios;
- conocimiento;
- tickets;
- webhooks e integraciones entrantes;
- agentes y módulos externos.
El catálogo mostrado al crear la clave y la respuesta de capacidades son la fuente de verdad para cada espacio. Solicita lectura y escritura por separado y evita scopes globales si la integración solo necesita una operación.
Gestión de claves¶
- guarda la clave en un gestor de secretos;
- no la subas al repositorio ni la incluyas en capturas;
- limita quién puede verla;
- rota la clave periódicamente y después de cualquier exposición;
- revócala al retirar una integración.
Respuestas y trazabilidad¶
Conserva el código HTTP y el request_id que devuelva NexGestión. Ante un 401 revisa la credencial; ante un 403, el scope o el acceso del espacio. No intentes solucionar un 403 ampliando permisos sin revisar antes la necesidad real.