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

# Registrar agente

> Registrar una nueva identidad de agente de máquina con par de claves criptográficas y permisos con ámbito

# Registrar Agente

`POST /v1/agents`

Registra una nueva identidad de agente de máquina para el inquilino autenticado. La plataforma genera un par de claves Ed25519 para el agente, asigna una ID de agente compatible con MAIP y registra la clave inicial en el libro mayor del historial de claves. Los agentes recién registrados comienzan con el estado `active` y una puntuación de confianza inicial de `0.500`.

> [!NOTE]
>
> El número de agentes que puede registrar depende de su plan de facturación. Si
> excede el límite de su plan, la API devuelve `402 Payment Required`. Póngase en contacto con ventas
> para límites de agentes de nivel empresarial.

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

**id** `string`

Clave primaria UUID interna.

**agent\_id** `string`

Identificador de agente compatible con MAIP en formato `maip:<tenant8>:<ulid>`. Use este valor
en todas las llamadas API posteriores que hagan referencia a este agente.

**tenant\_id** `string`

UUID del inquilino propietario.

**agent\_type** `string`

El tipo de agente registrado.

**display\_name** `string`

Nombre del agente legible por humanos.

**description** `string`

Descripción del agente, si se proporciona.

**trust\_level** `string`

Nivel de confianza inicial. Los agentes recién registrados comienzan en `"authenticated"`.

**trust\_score** `number`

Puntuación de confianza numérica (0.0 a 1.0). Los agentes recién registrados comienzan en `0.500`.

**status** `string`

Estado del ciclo de vida del agente. Siempre `"active"` en la creación.

**public\_key** `string`

Clave pública Ed25519 codificada en Base64url generada para este agente. Almacene esto
de forma segura para la verificación de firmas.

**key\_id** `string`

Identificador único para la clave de firma del agente. Referenciado en recibos y
atestaciones.

**scopes** `string[]`

Los alcances efectivos asignados al agente.

**metadata** `object`

El objeto de metadatos, si se proporciona.

**delegation\_depth** `number`

Profundidad actual de la cadena de delegación. Siempre `0` para agentes registrados directamente.
La profundidad máxima es `8` por protocolo MAIP.

**created\_by\_user\_id** `string`

UUID del usuario que registró el agente, si se autenticó mediante un token de usuario.

**expires\_at** `string`

Marca de tiempo de vencimiento, si está configurada.

**created\_at** `string`

Marca de tiempo de creación ISO 8601.

**updated\_at** `string`

Marca de tiempo de última actualización ISO 8601.

### Ejemplo

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "llm",
    "display_name": "Customer Support Bot",
    "description": "Handles Tier-1 customer support inquiries via chat",
    "scopes": ["data:read", "tool:search.web", "!data:delete"],
    "metadata": {
      "team": "support",
      "model": "claude-3.5-sonnet",
      "environment": "production"
    }
  }'
```


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/agents
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/agents:
    post:
      tags:
        - Machine Identity
      summary: Registrar agente
      description: >-
        Registrar una nueva identidad de agente de máquina. Devuelve el registro
        del agente, incluida una clave pública generada y una puntuación de
        confianza inicial.
      operationId: maip.agents.register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_type:
                  type: string
                  description: Clasificación del agente
                  enum:
                    - orchestrator
                    - worker
                    - inference
                    - pipeline
                    - service
                    - bot
                    - llm
                description:
                  type: string
                  description: Descripción de texto libre del propósito del agente
                display_name:
                  type: string
                  description: Nombre del agente legible por humanos
                  maxLength: 256
                expires_at:
                  format: date-time
                  nullable: true
                  type: string
                metadata:
                  description: Metadatos arbitrarios de clave-valor
                scopes:
                  items:
                    type: string
                  type: array
                  description: Ámbitos de permiso concedidos al agente
              type: object
              required:
                - display_name
      responses:
        '201':
          description: Agente registrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipAgent'
        '400':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticación requerida
          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:
    MaipAgent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        agent_type:
          type: string
          enum:
            - orchestrator
            - worker
            - inference
            - pipeline
            - service
            - bot
            - llm
        display_name:
          type: string
          maxLength: 256
        description:
          type: string
        status:
          type: string
          enum:
            - active
            - suspended
            - revoked
        scopes:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        trust_score:
          type: number
          format: float
          minimum: 0
          maximum: 1
        public_key:
          type: string
          description: Clave pública codificada en Base64
        session_count:
          type: integer
        keys:
          type: array
          items:
            type: object
            properties:
              kid:
                type: string
              algorithm:
                type: string
              public_key:
                type: string
              status:
                type: string
                enum:
                  - active
                  - disabled
                  - expired
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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.