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

# Autenticacion

> Como autenticar tus peticiones a la API de Thaliq

Todas las peticiones a la API de Thaliq requieren una **API Key** para identificar tu tenant.

## API Key

Incluye tu API Key en el header `X-API-Key`:

```bash theme={null}
curl -H "X-API-Key: tq_live_xxx" \
  https://api.thaliq.com/api/agent/stream?q=Hola
```

Las API Keys se crean desde la plataforma en la seccion **API Keys** y tienen el formato:

```
tq_live_xxxxxxxxxxxxxxxxxxxx
```

<Warning>
  La API Key solo se muestra una vez al crearla. Si la pierdes, crea una nueva y revoca la anterior.
</Warning>

## Headers

| Header               | Requerido | Descripcion                                                                                                                                            |
| -------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-API-Key`          |     Si    | Tu API Key del tenant. Resuelve tanto el tenant como el agente (segun a cual este asociada la key).                                                    |
| `X-Integration-Type` |     No    | `widget` o `sdk`. Controla que tools y MCP servers estan disponibles segun `requiresAuth`.                                                             |
| `X-User-Id`          |     No    | ID del usuario final en tu sistema (para tracking en LangFuse + DynamoDB). Imprescindible para metricas por usuario en B2B.                            |
| `X-Participant-Id`   |     No    | ID anonimo del visitante (fingerprint). Usado por el widget para conversaciones de usuarios anonimos. Si no se envia, el backend genera uno transient. |
| `X-MCP-Tokens`       |     No    | JSON `{"<serverId>":"<token>"}` con tokens de auth para MCP Servers (passthrough).                                                                     |
| `Authorization`      |     No    | `Bearer <jwt>` del usuario final. Passthrough para MCP servers que requieren JWT del usuario.                                                          |

## Tipos de integracion

El header `X-Integration-Type` controla que tools puede usar el agente:

| Valor          | Tools disponibles                    | Uso tipico                               |
| -------------- | ------------------------------------ | ---------------------------------------- |
| `widget`       | Solo tools con `requiresAuth: false` | Widget en sitios web (usuarios anonimos) |
| `sdk`          | Todas las tools                      | SDK/apps con usuarios autenticados       |
| *(sin header)* | Todas las tools                      | Platform, uso interno                    |

## Tracking de usuarios

Si quieres que las metricas en la plataforma muestren informacion por usuario, envia el header `X-User-Id`:

```bash theme={null}
curl -H "X-API-Key: tq_live_xxx" \
     -H "X-User-Id: usr_abc123" \
     https://api.thaliq.com/api/agent/stream?q=Hola
```

Este header es **opcional** y se usa para tracking/analytics. No afecta la autenticacion.

## MCP Token Passthrough

Si tus MCP Servers requieren autenticacion del usuario final, puedes enviar tokens por server ID:

```bash theme={null}
curl -H "X-API-Key: tq_live_xxx" \
     -H 'X-MCP-Tokens: {"server-financiero": "eyJhb...", "server-crm": "sk-xxx"}' \
     https://api.thaliq.com/api/agent/stream?q=Consulta+mi+saldo
```

Cada token se rutea automaticamente al MCP Server correspondiente. Los tokens nunca se almacenan en Thaliq.

## Seguridad

* **API Keys** son publicas por diseno (visibles en el widget). Solo dan acceso a tools publicas cuando se usa `X-Integration-Type: widget`.
* **SHA-256**: Thaliq almacena solo el hash de la key, no la key original.
* **MCP Tokens**: Se pasan directamente al MCP Server (passthrough), nunca se almacenan.
* **CORS**: La API permite peticiones desde cualquier origen.