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

# Conceptos Fundamentales

> Comprender inquilinos, emisores, atestaciones y verificación.

Esta guía explica los bloques de construcción fundamentales de la plataforma Truthlocks. Comprender estos conceptos es esencial para una integración efectiva.

## Inquilinos

Un **inquilino** es la unidad organizativa de nivel superior en Truthlocks. Cada inquilino representa un cliente u organización distinto con aislamiento completo de datos.

| Propiedad | Descripción |
| - | - |
| `id` | UUID único que identifica al inquilino |
| `name` | Nombre de la organización legible por humanos |
| `slug` | Identificador seguro para URL (por ejemplo, `acme-corp`) |
| `tier` | Nivel de suscripción: FREE, STARTER, PROFESSIONAL, ENTERPRISE |
| `status` | ACTIVO, SUSPENDIDO o ELIMINADO |

### Controles de multi-tenencia

* **Aislamiento de datos:** Los datos de cada inquilino están completamente aislados a nivel de base de datos
* **Límites de Recursos:** Los límites de tasa y las cuotas se aplican por inquilino
* **Alcance de la clave API:** Las claves API están vinculadas a un único inquilino y no pueden acceder a los datos de otros inquilinos
* **Separación de auditoría:** Los registros de auditoría están particionados por inquilino

## Emisores

Un **emisor** es una entidad que puede crear y firmar atestaciones. Los emisores representan organizaciones, instituciones o servicios que hacen reclamaciones sobre sujetos.

> [card] Identidad
>
> Cada emisor tiene un dominio verificado (por ejemplo, `acme.edu`) que establece su
> identidad en el mundo real.

> [card] Claves criptográficas
>
> Los emisores registran las claves públicas Ed25519 utilizadas para verificar las firmas de atestación.

> [card] Estado de confianza
>
> Los nuevos emisores se activan inmediatamente al crearse. Los niveles de confianza más altos requieren una revisión de la solicitud: ACTIVO → SUSPENDIDO.

> [card] Nivel de confianza
>
> BÁSICO, VERIFICADO o PREMIUM según la profundidad de la verificación de identidad.

### Ciclo de vida del emisor

```text theme={null}
                    ┌──────────────┐
                    │   CREATED    │
                    └───────┬──────┘
                            │ auto-activated
                            ▼
                    ┌──────────────┐
                    │    ACTIVE    │  ← Ready to mint (BASIC trust)
                    └───────┬──────┘
                            │
            suspend │               │ apply for higher tier
                    ▼               ▼
            ┌──────────────┐  ┌──────────────┐
            │   SUSPENDED  │  │   IN REVIEW  │
            └──────────────┘  └───────┬──────┘
                                      │
                              approve │ reject
                              ▼               ▼
                      ┌──────────────┐  ┌──────────────┐
                      │    ACTIVE    │  │   REJECTED   │
                      │ (higher tier)│  │ (keeps BASIC)│
                      └──────────────┘  └──────────────┘
```

> [!NOTE]
>
> Los nuevos emisores se activan inmediatamente con el nivel de confianza **Básico**. No se requiere aprobación manual para comenzar a acuñar atestaciones. Para actualizar a un nivel de confianza superior (Organización Verificada, Entidad Gubernamental o Institución Acreditada), envíe una [solicitud de emisor](https://docs.truthlocks.com/es/guides/issuer-applications.md) para su revisión.

## Atestaciones

Una **atestación** es una reclamación criptográficamente firmada hecha por un emisor sobre un sujeto. Las atestaciones son el primitivo central del sistema Truthlocks.

### Estructura de atestación

```json theme={null}
{
  "id": "uuid", // Unique identifier
  "issuer_id": "uuid", // Who signed it
  "kid": "string", // Key used to sign
  "status": "VALID", // Current status
  "payload": {
    "subject": "string", // Who/what the claim is about
    "claim": "string", // Type of claim (e.g., "verified_email")
    "value": "any", // The actual claim data
    "metadata": {} // Optional additional data
  },
  "signature": "base64", // Ed25519 signature
  "log_index": 42, // Position in transparency log
  "created_at": "datetime"
}
```

### Propiedades de atestación

| Propiedad | Descripción |
| - | - |
| **Inmutable** | Una vez creados, la carga útil y la firma no pueden modificarse |
| **Revocable** | Los emisores pueden revocar atestaciones, actualizando el estado a REVOCADO |
| **Supersedable** | Los emisores pueden [sustituir](https://docs.truthlocks.com/es/api-reference/attestations/supersede.md) una atestación con una nueva versión, creando una cadena auditable mientras se conserva la original |
| **Portátil** | El ID de atestación se puede compartir y verificar en cualquier lugar |
| **Auditable** | Cada operación se registra en el registro de transparencia |

## Protecciones al consumidor

Una **protección al consumidor** es una atestación creada a través del flujo simplificado de [acuñación para el consumidor](https://docs.truthlocks.com/es/api-reference/consumer/mint.md), diseñado para creadores individuales. Usted aplica un hash a su archivo en el lado del cliente (SHA-256) y envía el hash junto con metadatos como título, categoría y tipo de contenido. Truthlocks aprovisiona su identidad de firma automáticamente en el primer uso.

La respuesta de acuñación del consumidor incluye:

| Campo | Descripción |
| - | - |
| `protection_id` | ID único para el registro de protección |
| `attestation_id` | El ID de atestación subyacente (utilizado para la verificación) |
| `content_hash` | El hash SHA-256 que envió, devuelto para confirmación |
| `protected_at` | Marca de tiempo exacta cuando se protegió el contenido |
| `verify_url` | URL de la página de prueba pública que puedes compartir con cualquiera |
| `status` | Estado de confirmación (`protected`) |

Cada protección genera una página de prueba pública. Cualquiera puede obtener los metadatos de la página de prueba a través de `GET /v1/public/proof/{attestation_id}` — no se requiere autenticación. Este endpoint está diseñado para renderizar páginas de prueba y generar vistas previas de enlaces de Open Graph para URLs compartidas. Consulte el [endpoint de metadatos de prueba](https://docs.truthlocks.com/es/api-reference/consumer/proof-metadata.md) para obtener más detalles.

## Señales de riesgo

Una **señal de riesgo** es una observación puntuada de una fuente de detección de fraude: huella digital del dispositivo, reputación de IP, verificación de correo electrónico, análisis de documentos o su propio motor de reglas. Puede ingerir señales directamente a través de la API, o enviar eventos de identidad sin procesar y dejar que la plataforma los normalice en señales automáticamente.

Cada señal incluye:

| Campo | Descripción |
| :- | :- |
| `signal_source` | De dónde provino la señal (por ejemplo, `device_fingerprint`, `ip_reputation`, `login`) |
| `signal_type` | Qué se detectó (por ejemplo, `velocity`, `geo_anomaly`, `ato`, `deepfake`) |
| `risk_score` | Puntuación de riesgo de `0` (seguro) a `100` (alto riesgo) — las puntuaciones iguales o superiores a 80 activan la revisión automática |
| `subject_id` | Identificador de la entidad que se está evaluando |
| `subject_type` | El tipo de entidad: `user`, `issuer`, `session`, `device`, `ip`, o `attestation` |
| `payload` | Metadatos arbitrarios (direcciones IP, geolocalización, razones) |

### Normalización de eventos

En lugar de construir señales de riesgo manualmente, puede enviar eventos de identidad sin procesar —inicios de sesión fallidos, firmas no válidas, sospechosos de deepfake— a `POST /v1/risk/events`. La plataforma asigna automáticamente cada evento a un tipo de señal canónico y una puntuación de riesgo base. Consulte la [referencia de la API de normalización de eventos de identidad](https://docs.truthlocks.com/es/api-reference/risk/normalize-event.md).

Las señales de riesgo están completamente aisladas por inquilino utilizando [seguridad a nivel de fila](https://docs.truthlocks.com/es/security/rls.md) y forman la base del Firewall de Identidad Antifraude. Consulte la [guía de señales de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md) para obtener detalles de integración.

## Agentes de máquina

Un **agente de máquina** es un agente de IA, bot o servicio automatizado registrado con el [Protocolo de Identidad de Agente de Máquina (MAIP)](https://docs.truthlocks.com/es/guides/machine-identity.md). Cada agente obtiene un identificador único (`maip-agent:<ulid>`) y un par de claves Ed25519 para firmar recibos.

| Campo | Descripción |
| :- | :- |
| `agent_id` | Identificador MAIP único para el agente |
| `name` | Nombre de agente legible (p. ej., `order-processor`) |
| `type` | Tipo de agente: `autonomous`, `supervised`, `delegated` o `system` |
| `scopes` | Ámbitos de permiso que el agente está autorizado a usar |
| `status` | Estado del ciclo de vida: `active`, `suspended`, o `revoked` |
| `trust_score` | Puntuación de confianza conductual continua de 0 a 100 |

Los agentes operan dentro de **sesiones**, contextos de ejecución de corta duración y con alcance limitado con caducidad automática. Cada acción que realiza un agente genera un **recibo** criptográficamente firmado que se encadena al recibo anterior para pistas de auditoría a prueba de manipulaciones. Nueve tipos de recibos cubren el ciclo de vida completo del agente: génesis, delegación, acción, revocación, atestación de datos, atestación de modelo, cumplimiento, reclamación de verdad y verificación.

Consulte la [guía de identidad de la máquina](https://docs.truthlocks.com/es/guides/machine-identity.md) para la configuración y la [guía de autorización del agente](https://docs.truthlocks.com/es/guides/agent-authorization.md) para el modelo de alcance y sesión.

## Paquetes de prueba

Un **paquete de prueba** es un paquete autocontenido que incluye todo lo necesario para verificar una atestación offline, sin contactar a los servidores de Truthlocks.

```json theme={null}
{
  "attestation": { ... },       // Full attestation object
  "issuer": {
    "id": "uuid",
    "name": "Acme University",
    "domain": "acme.edu",
    "trust_level": "VERIFIED"
  },
  "public_key": {
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "transparency_proof": {
    "log_index": 42,
    "root_hash": "sha256:...",
    "inclusion_proof": ["hash1", "hash2", ...]
  }
}
```

> [!NOTE]
>
> **Caso de uso:** Los paquetes de pruebas son ideales para escenarios en los que los verificadores pueden estar
> sin conexión o desea verificar de forma independiente sin llamadas a la API.

## Modelo de verificación

La verificación de Truthlocks comprueba múltiples capas para determinar si una atestación debe ser confiable:

**1. Verificación criptográfica**

Verifique que la firma Ed25519 coincide con la carga útil utilizando la clave pública del emisor.
clave.

**2. Verificación de estado**

Verifique si la atestación ha sido revocada o reemplazada por el emisor. Las atestaciones reemplazadas se vinculan a su reemplazo a través de `superseded_by_attestation_id`.

**3. Estado de confianza del emisor**

Confirme que el emisor está en estado ACTIVO y no suspendido.

**4. Validez de la clave**

Verifique que la clave de firma estaba activa en el momento de la creación de la atestación.

## Próximos pasos

> [card] [Entornos](https://docs.truthlocks.com/environments.md)
>
> Aprende sobre los entornos de desarrollo vs. producción y su configuración.

> [card] [Autenticación](https://docs.truthlocks.com/security/auth.md)
>
> Profundice en las claves API, los tokens JWT y la integración OAuth.


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