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

# Autenticación

> Métodos de autenticación de API, gestión de claves y mejores prácticas de seguridad.

Truthlocks admite múltiples métodos de autenticación para asegurar el acceso a la API. Esta guía cubre las claves API, los tokens JWT y las mejores prácticas de seguridad.

## Métodos de autenticación

> [card] Claves API
>
> Credenciales de larga duración para comunicación de servidor a servidor. Recomendado para
> servicios de backend.

> [card] Tokens de portador (JWT)
>
> Tokens de corta duración para usuarios autenticados. Ideales para aplicaciones frontend
> y contexto de usuario.

## Claves de API

Truthlocks tiene dos tipos de claves API según cómo utilice la plataforma:

| Tipo | Prefijo | Creado a partir de | Caso de uso |
| :- | :- | :- | :- |
| **Clave de inquilino** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | Integraciones de servidor a servidor, flujos de trabajo empresariales |
| **Clave de consumidor** | `tlk_` | [Portal de Verify](https://verify.truthlocks.com) | Acceso personal a la API para protección y verificación de contenido |

### Pasando su clave

Incluya su clave API utilizando cualquiera de estos encabezados:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "X-API-Key: tl_live_your_api_key"
```

También puede usar el encabezado `Authorization` con el esquema `ApiKey`:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "Authorization: ApiKey tl_live_your_api_key"
```

Estos formatos autentican los puntos finales habilitados con clave API. Algunas operaciones requieren un token de portador de usuario y comprobaciones de rol; los puntos finales de salud pública no necesitan ninguno. `X-API-Key` es más común en los ejemplos a lo largo de esta documentación.

## Claves API de inquilino

Las claves de inquilino son el método de autenticación principal para las organizaciones que utilizan Truthlocks. Están limitadas a un inquilino y admiten permisos granulares.

### Estructura clave

```text theme={null}
tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: test | live
└── Prefix: tl (Truthlocks)
```

### Alcances

Las claves API de inquilino se pueden restringir a permisos específicos:

| Alcance | Permisos |
| - | - |
| `attestations:mint` | Crear nuevas atestaciones |
| `attestations:read` | Leer detalles de atestación y paquetes de prueba |
| `attestations:revoke` | Revocar atestaciones |
| `issuers:read` | Ver información del emisor |
| `issuers:write` | Crear y gestionar emisores |
| `users:read` | Ver usuarios y roles |
| `users:write` | Invitar usuarios, gestionar roles |
| `audit:read` | Consultar registros de auditoría |

> [!NOTE]
>
> **Principio de privilegio mínimo:** Conceda solo los alcances que su aplicación
> realmente necesita. Una clave con solo `attestations:mint` no debería tener también
> `users:write`.

### Creación de una clave de inquilino

#### Vía consola

1. Navegue a [console.truthlocks.com/api-keys](https://console.truthlocks.com/api-keys)
2. Haga clic en "Crear clave de API".
3. Ingrese un nombre descriptivo (por ejemplo, "Backend de Producción")
4. Seleccione el entorno (producción o sandbox) y los alcances requeridos
5. Copie la clave inmediatamente — no se mostrará de nuevo

#### Vía API

```bash Request theme={null}
curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'
```

```json Response theme={null}
{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}
```

> [!WARNING]
>
> **Crítico:** El campo `secret` se devuelve solo una vez en el momento de la creación. Almacene
> inmediatamente en un gestor de secretos.

## Claves de API de consumidor

Las claves de consumidor permiten a los usuarios individuales acceder a las API de protección y verificación de forma programática, por ejemplo, para acuñar atestaciones desde una canalización de CI o integrar la protección de contenido en sus propias herramientas.

### Detalles clave

* Cada cuenta admite hasta **5 claves activas**.
* Las claves caducan automáticamente después de **90 días**.
* Las claves revocadas o caducadas no se pueden reactivar; cree una nueva en su lugar.

### Ámbitos fijos

Las claves de consumidor se emiten con un conjunto fijo de alcances que no se pueden personalizar:

| Alcance | Permisos |
| :- | :- |
| `consumer:read` | Leer su perfil y configuración de consumidor |
| `consumer:write` | Actualice su perfil y configuración de consumidor |
| `attestations:mint` | Acuñar nuevas atestaciones |
| `attestations:read` | Leer sus atestaciones |
| `verify:read` | Verificar atestaciones |

### Creación de una clave de consumidor

**1. Abrir configuración**

En la barra lateral del portal de verificación, ve a **Configuración > Claves de API**.

**2. Crear una clave**

Haga clic en **Crear clave API**, ingrese un nombre descriptivo y confirme. El completo
el secreto se muestra una vez; cópielo y guárdelo de forma segura.

**3. Usar la clave**

Pasa la clave en el encabezado `X-API-Key` con cada solicitud:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"
```

Para obtener detalles completos sobre la gestión de claves de consumidor, consulte la [guía del portal del consumidor](https://docs.truthlocks.com/es/guides/consumer-portal.md#api-keys).

## Tokens de portador (JWT)

Los tokens JWT se utilizan cuando necesita realizar llamadas a la API en nombre de un usuario autenticado, como desde una aplicación web o móvil.

### Uso de tokens de portador

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### Estructura del token

```json theme={null}
{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}
```

### Vida útil del token

| Tipo de token | Vida útil | Actualizar |
| - | - | - |
| Token de acceso | 1 hora | Mediante token de actualización |
| Token de actualización | 30 días | Mediante reautenticación |

## MFA de autenticador para cuentas de Console

En Console, abra **Configuración → Seguridad → Autenticador MFA** para conectar Google Authenticator u otra aplicación de autenticación basada en tiempo.

1. Confirme su contraseña local actual de Truthlocks.
2. Escanee el código QR privado o ingrese la clave de configuración en su autenticador como una cuenta basada en tiempo.
3. Ingrese el código de seis dígitos de la aplicación para habilitar la MFA.
4. Guarde los diez códigos de recuperación que se muestran después de la confirmación. Se muestran una vez, y cada código funciona una vez.

Los nuevos inicios de sesión requieren el segundo factor después de su contraseña o de su proveedor de identidad empresarial. El paso de verificación expira después de cinco minutos. Los códigos incorrectos repetidos bloquean temporalmente la verificación de la cuenta. Un código que ya ha sido aceptado no puede ser reutilizado.

Para reemplazar los códigos de recuperación o deshabilitar la MFA, confirme su contraseña y un código de autenticador nuevo o un código de recuperación no utilizado. Reemplazar los códigos de recuperación invalida el conjunto anterior. Los usuarios de SSO que nunca hayan establecido una contraseña local de Truthlocks pueden usar el flujo de restablecimiento de contraseña para su correo electrónico registrado antes de la inscripción.

La inscripción de MFA se aplica a su propia cuenta. No inscribe a otros miembros ni impone un requisito de MFA en todo el espacio de trabajo. Habilitar MFA no revoca automáticamente las sesiones existentes. Las claves de API siguen siendo credenciales de sistema separadas.

## Mejores prácticas de seguridad

> [card] ✅ Usar gestión de secretos
>
> Almacene las claves API en Google Secret Manager, HashiCorp Vault o similar. Nunca
> claves codificadas en el código de la aplicación.

> [card] ✅ Rotar claves regularmente
>
> Cree nuevas claves y revoque las antiguas periódicamente. Use nombres descriptivos con
> fechas (por ejemplo, "Backend-2026-Q1").

> [card] ✅ Restringir ámbitos
>
> Concede solo los permisos que realmente se necesiten. Revisa y audita los alcances de las claves
> regularmente.

> [card] ❌ Nunca exponer en el frontend
>
> Las claves de API nunca deben incluirse en JavaScript del lado del cliente. Utilice tokens JWT
> para autenticación frontend.

> [card] ❌ Nunca confirmar en Git
>
> Utilice variables de entorno o gestión de secretos. Añada `.env*` a
> `.gitignore`.

## Próximos pasos

> [card] [Portal del consumidor](https://docs.truthlocks.com/guides/consumer-portal.md)
>
> Gestiona claves de API de consumidor, protecciones y configuraciones.

> [card] [Entornos](https://docs.truthlocks.com/environments.md)
>
> Configuración de sandbox vs. producción y URLs base.

> [card] [RBAC y permisos](https://docs.truthlocks.com/security/rbac.md)
>
> Comprenda los roles, permisos y control de acceso.

> [card] [Registros de auditoría](https://docs.truthlocks.com/security/audit.md)
>
> Rastree toda la actividad de la API y los eventos de seguridad.


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