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

# Credentials

> API keys y access keys del agente — para autenticar widget, SDK e integraciones

La tab **Credentials** (`thaliq.com/agents/:agentId/credentials`) administra las claves que autentican peticiones a tu agente. Hay dos tipos: **API Keys** (para integraciones server-side y SDK) y **Access Keys** (para widget publico).

<Note>
  Antes esta tab se llamaba **API Keys**. Se renombro a **Credentials** porque ahora maneja los dos tipos. La ruta vieja `/agents/:agentId/api-keys` redirige automaticamente.
</Note>

## API Key vs Access Key

| Aspecto                   | API Key                                                        | Access Key                                                            |
| ------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Prefijo**               | `tq_live_` (prod) · `tq_test_` (test)                          | `tq_ak_`                                                              |
| **Visibilidad**           | Solo se muestra una vez al crear                               | Visible siempre desde el workspace                                    |
| **Backend**               | Hash SHA-256 (no se almacena el plaintext)                     | Plaintext almacenado (es la key del widget publico)                   |
| **Uso tipico**            | SDK, integraciones server-side, llamadas autenticadas a la API | Widget embebible en HTML, snippets publicos                           |
| **Por que la diferencia** | Las API keys no deben quedar en codigo cliente                 | Las access keys ya viven en HTML publico, no tiene sentido ofuscarlas |

<Tip>
  Si dudas: para **widget** en sitios web -> Access Key. Para **SDK** en backend o app autenticada -> API Key.
</Tip>

## Crear una credencial

1. Ir a **Agente > Credentials**
2. Switch en la cabecera para elegir el tipo (`API_KEY` / `ACCESS_KEY`)
3. Click en **Crear**
4. Asignar un nombre descriptivo (ej: "Widget produccion", "SDK staging")
5. (Opcional) Marcar como **test key** para una API Key (`tq_test_` en lugar de `tq_live_`)
6. Copiar la key generada

<Warning>
  Las **API Keys solo se muestran una vez al crear**. Guardalas en un lugar seguro (vault, password manager, secret manager del cloud). Si la perdes, hay que crear una nueva.

  Las **Access Keys** (`tq_ak_`) estan siempre visibles desde el workspace — no requieren respaldo manual.
</Warning>

## Routing al agente

Las credenciales son **propias del agente**. Eso significa que cualquier request hecha con esa key ya viene "ruteada" al agente padre — no necesitas pasar `agentId` en el body o query.

| Key                                 | Asociada a           | Comportamiento                                  |
| ----------------------------------- | -------------------- | ----------------------------------------------- |
| `tq_live_aaa` (Agente "Soporte")    | Agente Soporte       | Las requests con esta key van al agente Soporte |
| `tq_live_bbb` (Agente "Ventas")     | Agente Ventas        | Las requests con esta key van al agente Ventas  |
| `tq_live_ccc` sin agente especifico | (default del tenant) | Caen al agente default del tenant               |

**Override por request:** podes pasar `agentId` en el body (`POST /chat`) o como query param (`GET /stream`) para forzar un agente distinto al de la key.

<Note>
  Si **eliminas un agente** desde el workspace, las credenciales que apuntaban a el quedan **revertidas al agente default** automaticamente (no se invalidan). Asi un cambio interno no rompe una integracion en produccion. Si querias revocarlas, hacelo explicitamente desde la tab.
</Note>

## Formato de las keys

```
tq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # API Key produccion
tq_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # API Key test
tq_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx     # Access Key (widget)
```

## Usar una credencial

### Widget (con Access Key)

```html theme={null}
<script
  src="https://cdn.thaliq.com/widget.js"
  data-api-key="tq_ak_xxx"
></script>
```

### SDK (con API Key)

```typescript theme={null}
import { Thaliq } from '@thaliq/sdk';

const thaliq = new Thaliq({
  apiKey: 'tq_live_xxx',
});
```

### Peticiones HTTP directas

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

## Revocar una credencial

Si una key se ve comprometida o ya no la necesitas:

1. Ir a **Agente > Credentials**
2. Click en el menu de la key
3. Click en **Revocar**
4. Confirmar

<Warning>
  Revocar es **irreversible**. Las integraciones que usen esa key dejan de funcionar inmediatamente.
</Warning>

## Buenas practicas

* **Una key por entorno** — keys separadas para produccion, staging y desarrollo
* **Rotar periodicamente** — crear key nueva, actualizar la integracion, revocar la vieja
* **No compartir keys** — cada integracion deberia usar su propia
* **Monitorear consumo** — revisar [Usage](/platform/usage) por user agent / origen para detectar uso raro
* **Test keys para staging** — usa el flag `is test` (`tq_test_`) en ambientes no productivos

## Seguridad

* **API Keys**: Thaliq almacena solo el **hash SHA-256** del plaintext. La key original solo existe en tu lado.
* **Access Keys**: el plaintext si se almacena (es publico por diseno) — pero solo da acceso a tools con `requiresAuth: false`.
* **Aislamiento por tenant**: una key del tenant A nunca puede acceder a recursos del tenant B.
* **Filtro por integracion**: el header `X-Integration-Type: widget` filtra automaticamente las tools sensibles, incluso si la access key se filtra.

## Que sigue

<CardGroup cols={2}>
  <Card title="Channels" icon="radio" href="/platform/channels">
    Donde activar el widget y SDK que consumen estas keys.
  </Card>

  <Card title="Widget overview" icon="message-square" href="/widget/overview">
    Como funciona el widget y que tools ve segun el tipo de key.
  </Card>

  <Card title="SDK overview" icon="code" href="/sdk/overview">
    Cuando usar el SDK con API key vs widget con access key.
  </Card>
</CardGroup>