> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autorización de Agente

> Autorización basada en alcance, gestión de sesiones e invocación de herramientas para agentes de IA.

# Autorización de Agente

Cada agente de IA en la plataforma Truthlocks opera bajo un estricto modelo de autorización. Los agentes deben estar registrados, tener alcances asignados y crear sesiones con límite de tiempo antes de poder realizar cualquier acción.

## Flujo de autorización

```
Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session
      │               │                │                │               │
      ▼               ▼                ▼                ▼               ▼
  agent_id        scope_ids       session_token    audit_logged      cleanup
```

> [!TIP]
>
> Todos los endpoints de autorización de agentes —ámbitos, sesiones y herramientas— tienen un API playground interactivo. Abra cualquier endpoint en la referencia de la API [Sesiones y Herramientas de Agente](https://docs.truthlocks.com/es/api-reference/machine-identity/sessions/create.md) y haga clic en **Enviar** para probarlo contra el Sandbox.

## Modelo de alcance

Los alcances siguen un patrón jerárquico `resource:action`. Cuando un agente solicita una sesión, solo puede solicitar los alcances que se le asignaron en el registro.

### Definición de ámbitos personalizados

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "invoices:approve",
    "description": "Approve invoices up to configured threshold",
    "constraints": {
      "max_amount_cents": 500000,
      "require_dual_approval_above": 100000
    }
  }'
```

### Ámbitos incorporados

| Alcance | Descripción |
| - | - |
| `agents:read` | Listar e inspeccionar agentes |
| `agents:write` | Registrar y actualizar agentes |
| `receipts:write` | Recibos de acciones de acuñación |
| `attestations:read` | Leer datos de atestación |
| `attestations:write` | Crear nuevas atestaciones |
| `trust-scores:read` | Leer datos de puntuación de confianza |
| `trust-scores:compute` | Activar recálculo de puntuación de confianza |
| `delegations:offer` | Ofrecer delegación entre inquilinos |
| `delegations:accept` | Aceptar ofertas de delegación |
| `compliance:write` | Crear comprobaciones de cumplimiento |
| `orchestrations:execute` | Ejecutar flujos de trabajo multi-agente |
| `datasets:attest` | Atestar la procedencia del conjunto de datos |
| `models:attest` | Atestar el linaje del modelo |

## Gestión de sesiones

Las sesiones proporcionan contextos de ejecución con límite de tiempo con caducidad automática y lista de permitidos de IP opcional.

### Creación de una sesión

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write", "attestations:read"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"],
    "metadata": {
      "task": "process-quarterly-invoices",
      "initiated_by": "user:alice@corp.com"
    }
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "maip-session:01JYYYY",
  "agent_id": "maip-agent:01JXXXX",
  "token": "mst_live_...",
  "scopes": ["receipts:write", "attestations:read"],
  "expires_at": "2026-04-06T13:00:00Z",
  "status": "active"
}
```

### Ciclo de vida de la sesión

| Estado | Descripción |
| - | - |
| `active` | La sesión es válida y acepta solicitudes |
| `expired` | TTL transcurrido — limpieza automática |
| `terminated` | Finalizado explícitamente por el usuario o el sistema |
| `suspended` | Pausado debido a la detección de anomalías |

### Finalizar una sesión

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Task completed" }'
```

## Registro e invocación de herramientas

Los agentes pueden registrar las herramientas que exponen e invocar herramientas registradas por otros agentes (sujeto a comprobaciones de alcance).

### Registrar una herramienta

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "name": "generate-invoice",
    "description": "Generate PDF invoice from order data",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "format": { "type": "string", "enum": ["pdf", "html"] }
      },
      "required": ["order_id"]
    }
  }'
```

### Invocar una herramienta

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools/invoice-generator/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'
```

Cada invocación de herramienta es:

1. **Alcance verificado**: la sesión debe tener el alcance requerido.
2. **Con límite de velocidad**: según la cuota de invocación de herramientas de su plan.
3. **Registrado en auditoría** — entrada/salida completa registrada en el registro de auditoría
4. **Medido** — contado contra sus derechos de facturación

## Mejores prácticas de seguridad

> [!WARNING]
>
> Nunca incruste tokens de sesión en el código del lado del cliente. Los tokens de sesión otorgan el alcance completo de la sesión y deben tratarse como secretos.

1. **Principio de privilegio mínimo**: Solicite solo los alcances necesarios para la tarea actual.
2. **Sesiones de corta duración**: Utilice el TTL más corto posible (predeterminado: 1 hora).
3. **Lista de IP permitidas** — Restringir sesiones a rangos de red conocidos
4. **Rotar credenciales** — Regenerar las claves de firma del agente en un horario regular
5. **Monitorear puntuaciones de confianza** — Configure alertas cuando las puntuaciones de confianza caigan por debajo de los umbrales
6. **Use el interruptor de emergencia** — Revoque inmediatamente los agentes comprometidos

## Próximos pasos

> [card] [Políticas MAIP](https://docs.truthlocks.com/guides/maip-policies.md)
>
> Reglas de aplicación en tiempo de ejecución basadas en puntuaciones de confianza, alcances y profundidad de delegación.

> [card] [Puntuaciones de Confianza](https://docs.truthlocks.com/guides/trust-scores.md)
>
> Evaluación continua de la confianza conductual para los agentes.

> [card] [Delegación entre inquilinos](https://docs.truthlocks.com/guides/cross-tenant-delegation.md)
>
> Permitir que los agentes actúen a través de los límites organizacionales.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.