API & SDK
Autenticación
ShieldAgent utiliza autenticación mediante token Bearer para todas las solicitudes de API y proxy. Hay dos tipos de token: claves de agente para llamadas al proxy MCP, y claves API de administración para operaciones de gestión.
Tipos de token
Clave de agente
sa_live_…Uso: Autenticar solicitudes al proxy MCP. Limitada a un único agente dentro de un tenant.
Obtener: Panel → Agentes → [tu agente] → Claves, o mediante POST /agents/:id/keys
Clave API de administración
sa_admin_…Uso: Gestionar tenants, agentes, políticas y registros de auditoría mediante la API REST.
Obtener: Panel → Configuración → Claves API → Nueva clave
Realizar solicitudes autenticadas
Incluye el token en la cabecera Authorization :
bash
# MCP proxy request (agent key)
curl -X POST https://proxy.shieldagent.io/mcp \
-H 'Authorization: Bearer sa_live_YOUR_AGENT_KEY' \
-H 'Content-Type: application/json' \
-d '{"method": "tools/call", "params": {...}}'
# Management API request (admin key)
curl https://api.shieldagent.io/tenants \
-H 'Authorization: Bearer sa_admin_YOUR_ADMIN_KEY'Rotación de claves
Rota las claves de agente sin tiempo de inactividad usando el patrón de solapamiento de dos claves:
- 1.Genera una nueva clave — la clave antigua permanece activa.
- 2.Actualiza la configuración de tu agente para usar la nueva clave.
- 3.Verifica que la nueva clave funciona en la pestaña Eventos del panel.
- 4.Revoca la clave antigua.
Respuestas de error
401Cabecera Authorization ausente o con formato incorrecto
403Clave válida pero permisos insuficientes para esta operación
429Límite de tasa superado — consulta la cabecera Retry-After