> ## 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.

# Invocar herramienta

> Solicitar invocación de herramienta con validación de alcance, limitación de velocidad y generación de recibo de auditoría

# Invocar Herramienta

`POST /v1/tools/{toolName}/invoke`

Solicita la invocación de una herramienta registrada en nombre de un agente de máquina. La plataforma realiza una verificación de control de acceso de múltiples capas antes de otorgar el acceso:

1. **Estado del agente**: el agente debe estar `"active"`
2. **Verificación de alcance**: el agente debe tener el alcance requerido por la herramienta.
3. **Límite de velocidad** -- el agente no debe exceder el límite de velocidad por minuto de la herramienta
4. **Puerta de aprobación** -- si la herramienta requiere aprobación, la respuesta es `pending_approval`; el controlador actual no crea una solicitud de aprobación

Si todas las comprobaciones pasan, la invocación se registra. Los recibos de herramientas actuales utilizan un marcador de sistema en lugar de una firma criptográfica. Son registros de auditoría, no pruebas firmadas verificables de forma independiente.

> [!NOTE]
>
> Este punto de conexión realiza la **decisión de control de acceso** y registra la decisión. No actúa como proxy de la ejecución real de la herramienta. Su aplicación es
> responsable de llamar al punto final subyacente de la herramienta después de recibir una
> respuesta `"allowed"`.

### Autenticación

Requiere el encabezado `X-API-Key` o el token Bearer JWT. El espacio de trabajo se deriva de la credencial autenticada; no envíe `X-Tenant-ID`.

### Respuesta

**allowed** `boolean`

Si la invocación fue autorizada. `true` si todas las comprobaciones de control de acceso
aprobado.

**status** `string`

Estado de invocación. Uno de: `"allowed"`, `"denied"`, `"pending_approval"`.

**reason** `string`

Explicación legible por humanos cuando la invocación es denegada o está pendiente. No
presente cuando se permite.

**receipt\_id** `string`

Identificador de recibo único para la invocación, que enlaza con la pista de auditoría. Solo
presente cuando `status` es `"allowed"`.

**requires\_approval** `boolean`

`true` cuando la herramienta requiere aprobación humana. La invocación no se pone automáticamente en cola para aprobación.
Solo presente cuando `status` es `"pending_approval"`.

### Ejemplo: Invocación permitida

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "session_id": "maip-sess:a1b2c3d4:9f8e7d6c5b4a3210"
  }'
```

***

### Flujo de control de acceso

```
POST /v1/tools/{name}/invoke
  |
  +-- Is agent active?
  |     No  --> { allowed: false, status: "denied", reason: "agent is not active" }
  |
  +-- Does agent have required scope?
  |     No  --> { allowed: false, status: "denied", reason: "agent lacks required scope: ..." }
  |
  +-- Is rate limit exceeded?
  |     Yes --> { allowed: false, status: "denied", reason: "rate limit exceeded" }
  |
  +-- Does tool require approval?
  |     Yes --> { allowed: false, status: "pending_approval", requires_approval: true }
  |
  +-- Create receipt + record invocation
        --> { allowed: true, status: "allowed", receipt_id: "..." }
```

### Patrón de integración

Después de recibir una respuesta `"allowed"`, ejecute la herramienta y, opcionalmente, registre el resultado:

```bash theme={null}
# 1. Request invocation authorization
RESPONSE=$(curl -s -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH"}')

ALLOWED=$(echo "$RESPONSE" | jq -r '.allowed')
RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt_id')

# 2. Execute the tool only if explicitly authorized
if [ "$ALLOWED" = "true" ]; then
  RESULT=$(curl -s "https://serpapi.com/search?q=example&api_key=...")
  echo "Tool executed. Receipt: $RECEIPT_ID"
fi
```


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/tools/{toolName}/invoke
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/tools/{toolName}/invoke:
    post:
      tags:
        - Machine Identity
      summary: Invocar herramienta
      description: >-
        Verifica el acceso y registra una decisión de invocación. No ejecuta la
        herramienta. Los nuevos recibos requieren un firmante configurado y una
        clave de firma de agente activa válida. Una decisión de pending_approval
        no crea una solicitud de aprobación; solicite una revisión independiente
        explícitamente a través de /v1/approvals y haga cumplir el resultado en
        su aplicación.
      operationId: maip.tools.invoke
      parameters:
        - name: toolName
          in: path
          required: true
          schema:
            type: string
          description: Nombre de la herramienta registrada.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_id:
                  type: string
                session_id:
                  type: string
                  description: Sesión activa para invocar bajo
                  format: uuid
              type: object
              required:
                - agent_id
      responses:
        '200':
          description: Resultado de la invocación de la herramienta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipToolInvocationResult'
        '400':
          description: Error de validación o falta de coincidencia de esquema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticación requerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Herramienta o sesión no encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Límite de velocidad excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipToolInvocationResult:
      type: object
      properties:
        result:
          type: object
          additionalProperties: true
        receipt_id:
          type: string
          format: uuid
        execution_ms:
          type: integer
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Código de error legible por máquina
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error legible por humanos
        http_status:
          type: integer
          description: Código de estado HTTP
        retry_after_ms:
          type: integer
          description: Milisegundos a esperar antes de reintentar (para límites de tasa)
        details:
          type: object
          description: Contexto de error adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

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