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

# Identidad de usuario

> Como identificar usuarios autenticados para acceder a tools protegidas

El SDK permite identificar al usuario actual de tu aplicacion. Esto habilita:

* **Tools protegidas**: Tools con `requiresAuth: true` solo estan disponibles con usuario identificado
* **MCP Token Passthrough**: Tokens del usuario se envian a MCP Servers para ejecutar acciones en su nombre
* **Tracking por usuario**: Metricas en la plataforma muestran actividad por usuario
* **Feedback vinculado**: Feedback de mensajes se asocia al usuario

## Identificar un usuario

Llama a `identify()` cuando el usuario hace login en tu app:

```typescript theme={null}
thaliq.identify({
  userId: 'usr_123',
  email: 'maria@empresa.com',
  name: 'Maria Garcia',
  token: 'jwt_del_usuario',        // Bearer token (passthrough para MCP)
  mcpTokens: {                      // Tokens especificos por MCP server
    'crm-server': 'token_crm',
    'erp-server': 'token_erp',
  },
});
```

### Campos

| Campo           | Requerido | Descripcion                                                  |
| --------------- | :-------: | ------------------------------------------------------------ |
| `userId`        |     Si    | ID del usuario en tu sistema                                 |
| `email`         |     No    | Email del usuario                                            |
| `name`          |     No    | Nombre del usuario                                           |
| `token`         |     No    | JWT/Bearer token (se envia como `Authorization: Bearer ...`) |
| `mcpTokens`     |     No    | Tokens por MCP Server ID (se envian en `X-MCP-Tokens`)       |
| `participantId` |     No    | ID de participante para tracking de conversaciones           |
| `metadata`      |     No    | Metadata adicional (key-value)                               |

## Limpiar identidad

Llama a `reset()` cuando el usuario hace logout:

```typescript theme={null}
thaliq.reset();
```

Esto limpia la identidad, los headers asociados y el estado de conversaciones.

## Headers que se envian

Cuando un usuario esta identificado, el SDK incluye automaticamente estos headers:

```
X-API-Key: tq_live_xxx                      (siempre)
X-Integration-Type: sdk                      (siempre)
X-User-Id: usr_123                          (de identify)
X-Participant-Id: part_456                  (de identify, si hay participantId)
Authorization: Bearer jwt_del_usuario       (de identify, si hay token)
X-MCP-Tokens: {"crm-server":"token_crm"}   (de identify, si hay mcpTokens)
```

## MCP Token Passthrough

Los tokens en `mcpTokens` se envian al backend, que los rutea al MCP Server correspondiente. Esto permite que el MCP Server ejecute acciones **en nombre del usuario** sin que Thaliq almacene credenciales.

```typescript theme={null}
// El usuario tiene acceso a dos MCP servers
thaliq.identify({
  userId: 'usr_123',
  mcpTokens: {
    'server-financiero': 'eyJhb...',  // Token para el server financiero
    'server-crm': 'sk-xxx',          // Token para el CRM
  },
});

// El agente puede ejecutar tools de ambos servers
const stream = thaliq.agent.stream('Consulta mi saldo y mis tickets abiertos');
```

## participantId

El campo `participantId` se usa para identificar al participante en conversaciones. Es util cuando un mismo `userId` puede tener multiples sesiones o dispositivos:

```typescript theme={null}
thaliq.identify({
  userId: 'usr_123',
  participantId: `sdk:usr_123`,  // Formato: "sdk:{userId}"
});
```

<Info>
  El backend usa `participantId` como clave en el GSI de DynamoDB para recuperar conversaciones del participante. Si no se envia, se genera automaticamente como `sdk:{userId}`.
</Info>

## Eventos

El SDK emite eventos cuando se identifica o limpia un usuario:

```typescript theme={null}
thaliq.on('identify', (userId) => {
  console.log(`Usuario identificado: ${userId}`);
});

thaliq.on('reset', () => {
  console.log('Identidad limpiada');
});
```

## Ejemplo completo

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

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

// Login de tu app
function onUserLogin(user: { id: string; jwt: string; mcpToken: string }) {
  thaliq.identify({
    userId: user.id,
    token: user.jwt,
    mcpTokens: {
      'mi-api': user.mcpToken,
    },
  });
}

// Logout de tu app
function onUserLogout() {
  thaliq.reset();
}

// El agente ahora puede ejecutar tools protegidas
async function askAgent(question: string) {
  const stream = thaliq.agent.stream(question);
  for await (const event of stream) {
    if (event.type === 'content.delta') {
      process.stdout.write(event.delta);
    }
  }
}
```