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

# Autenticación

> Proteja la API con Basic Auth, luego empareje cada cuenta de WhatsApp con código QR, emparejando código o contraseña.

GOWA tiene dos tipos separados de autenticación:

1. **Acceso API**: quién puede llamar a GOWA. Esta es HTTP Basic Auth.
2. **Emparejamiento de WhatsApp**: enlaza una cuenta de WhatsApp a una ranura de dispositivo, ya que vincularía WhatsApp Web.

## Acceso API: Auth Básica

Basic Auth es el único método de autenticación de API. No hay claves API o JWTs para llamadas REST.

Establece uno o más pares de `user:password`, separados por comas:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

Cada entrada debe contener un nombre de usuario y contraseña no vacíos. El listener, `APP_HOST=0.0.0.0`, se niega a iniciar sin credenciales completas. Para desarrollo local sin autenticación, enlace `APP_HOST=127.0.0.1`.

Si un proxy inverso autentifica cada llamada, `APP_ALLOW_UNAUTHENTICATED=true` o `--allow-unauthenticated=true` explícitamente permite un oyente no-loopback sin Auth. Restringe el acceso directo a ese oyente.

Enviar credenciales en cada petición:

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

Una credencial faltante o equivocada devuelve `401 Unauthorized`.

### Lo que no está detrás de la autenticación básica

| Ruta | Por qué |
| - | - |
| `GET /health` | Sonda de vida. Siempre en la raíz, ignorando `APP_BASE_PATH`. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | Llamado por Chatwoot. Registrado solo cuando `CHATWOOT_ENABLED=true` y protegido por `CHATWOOT_WEBHOOK_SECRET` en su lugar. Ver [Chatwoot](https://gowa-docs.mintlify.site/es/integrations/chatwoot.md). |
| Descubrimiento de MCP OAuth y los extremos `/oauth/*` | Sólo cuando `MCP_OAUTH_ENABLED=true`. Vea [Servidor MCP](https://gowa-docs.mintlify.site/es/integrations/mcp.md). |
| `GET /statics/*` | Imágenes QR, subidas y medios descargados. Se han celebrado antes de la Autorización Básica. Cualquiera que conozca una URL de archivo puede recuperarla. Sólo archivos validados JPEG, PNG, GIF y WebP en rutas de imágenes se muestran en línea. Otros archivos descargan como archivos adjuntos con un tipo de contenido no activo y `X-Content-Type-Options: nosniff`. Restringir el acceso de archivo en el proxy cuando sea necesario. |

Todo lo demás, incluyendo el panel de control en `/`, `/mcp` y `/ws`, requiere Basic Auth cuando está configurado.

### WebSocket

Los navegadores no pueden establecer cabeceras en conexiones WebSocket, así que `/ws` toma la credencial en la cadena de consulta:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`authorization` es `base64(user:password)`. Use TLS (`wss://`) y redacta la cadena de consulta en los registros de proxy. WebSocket comprueba el origen del navegador contra los mismos orígenes confiables utilizados para las solicitudes HTTP que cambian el estado. El hub WebSocket actual transmite eventos a todos los sockets conectados. Una consulta `device_id` selecciona el contexto del dispositivo para la conexión pero no aísla la entrega de eventos. Utilice los identificadores del dispositivo del evento para filtrar la vista del panel de control y permitir el acceso de la API sólo a las personas que llaman en confianza con todos los dispositivos.

Vea la [referencia de WebSocket](https://gowa-docs.mintlify.site/es/api-reference/websocket.md) para códigos de eventos, carga útil y un ejemplo de cliente.

### CORS

CORS permite cualquier origen por defecto. Restringirlo con `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` (separados por comas). Los encabezados de solicitud permitidos son `Origin`, `Content-Type`, `Accept`, `Authorization`, y `X-Device-Id`.

Las comprobaciones CORS y el origen del navegador son separadas. Un comodín de origen CORS no autoriza peticiones cambiantes de estado o WebSockets. GOWA confía en los orígenes específicos de CORS de la solicitud, `APP_TRUSTED_ORIGINS`, y en los orígenes configurados para el emisor de OAuth y la URL de devolución de llamada de Chatwoot. Para un panel separado, configure su origen exacto:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

Una mutación de navegador no confiable devuelve `403 CROSS_SITE_REQUEST_BLOCKED`. Esto también cubre rutas GET que inician sesión, reconectan o restablecen un enlace de invitación. Clientes como curl que no envían cabeceras de origen del navegador siguen funcionando.

Un origen `null` nunca es de confianza. Serve `gowa-ui.html` sobre HTTP o HTTPS en lugar de abrirlo como una URL `file://`. Behind a reverse proxy, preserve `Host`, configure proxies confiables con `X-Forwarded-Host`, o liste el origen público en `APP_TRUSTED_ORIGINS`.

## Vinculación de WhatsApp

Cada cuenta de WhatsApp vive en un **espacio de dispositivos**. Crea la ranura primero, luego empareja. Las rutas bajo `/devices/{device_id}` toman el dispositivo desde la ruta. Las rutas equivalentes `/app/*` usan la cabecera `X-Device-Id`.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### QR code

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

Abre `qr_link` y escanéalo desde el teléfono: **Ajustes → Dispositivos enlazados → Enlazar un dispositivo**. Solicitar un nuevo código después de `qr_duration` segundos. El panel de control de `/` muestra el QR directamente y actualiza directamente el WebSocket.

### Pairing code

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

La respuesta contiene `results.pair_code`, un código de 8 caracteres. En el teléfono, elige **Enlace con el número de teléfono en su lugar** y escríbelo. `phone` debe ser el número de la cuenta vinculada, con el código del país.

### Clave

Si el teléfono solicita la verificación de la clave de acceso durante el inicio de sesión QR, GOWA almacena un desafío WebAuthn y transmite `PASSKEY_REQUEST` en el WebSocket. El tablero maneja este flujo. Para manejarlo usted mismo:

1. `GET /app/passkey` devuelve el desafío pendiente.
2. `POST /app/passkey/response` envía la afirmación de WebAuthn (formato `PublicKeyCredential.toJSON()`).
3. Espere a `PASSKEY_CONFIRMATION`. Cuando `result.skip_handoff_ux` es verdadero, el flujo QR activo envía la confirmación automáticamente. De lo contrario, compare `result.code` con el código del teléfono, luego llame a `POST /app/passkey/confirm`.

Envía `X-Device-Id` en las tres llamadas.

### Comprobar el resultado

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

`results.is_connected` y `results.is_logged_in` son `true` una vez que la cuenta está vinculada. Las sesiones persisten en `storages/`, así que los reinicios no requieren emparejamiento de nuevo.

## Cerrando sesión y eliminando

| Accin | Endpoint | Efecto |
| - | - | - |
| Cerrar sesión | `POST /devices/{device_id}/logout` o `GET /app/logout` | Desvincula la cuenta de WhatsApp y elimina su sesión. La ranura permanece, para que puedas emparejarla de nuevo bajo el mismo ID. |
| Volver a conectar | `POST /devices/{device_id}/reconnect` o `GET /app/reconnect` | Vuelve a abrir la conexión de WhatsApp sin emparejar de nuevo. |
| Eliminar | `DELETE /devices/{device_id}` | Cerrar sesión, luego elimina la ranura junto con sus datos de sesión y chat. |

Una cuenta desvinculada del teléfono (dispositivos enlazados → Cerrar sesión) se cierra de la misma manera: la ranura permanece y necesita emparejarse de nuevo.

## Lista de seguridad

* Siempre establece `APP_BASIC_AUTH` con contraseñas fuertes en cualquier cosa accesible desde una red.
* Terminar TLS en un proxy inverso; las credenciales Basic Auth sólo están codificadas en base64.
* Restringir `APP_CORS_ALLOWED_ORIGINS` cuando una interfaz de navegador llame a la API.
* Genera un `WHATSAPP_WEBHOOK_SECRET` estable con `openssl rand -hex 32`. Los secretos de ejemplo vacíos o publicados son reemplazados por una clave aleatoria por proceso que cambia al reiniciar.
* Trata a `storages/` como sensible. Contiene todas las claves de sesión de la cuenta vinculadas. Nuevos archivos SQLite usan permisos de solo propietario, y los directorios creados para ellos usan `0700`. Proteja las copias de seguridad con el mismo cuidado.


## Related topics

- [Autenticación de API](https://gowa-docs.mintlify.site/es/api-reference/authentication.md)
- [Referencia API](https://gowa-docs.mintlify.site/es/api-reference/introduction.md)
- [Referencia de configuración](https://gowa-docs.mintlify.site/es/configuration.md)
- [Métricas del servidor](https://gowa-docs.mintlify.site/es/api-reference/metrics.md)
- [Inicio rápido](https://gowa-docs.mintlify.site/es/quickstart.md)


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