# Autenticación

> Referencia técnica de todos los mecanismos de autenticación de Rapid: Basic Auth para tus llamadas y la firma del webhook para las llamadas de Rapid.

Página: https://doc.rapidchargeback.com/es/referencia/autenticacao/

Esta página es la referencia técnica de todos los mecanismos de autenticación de Rapid.

## Tu aplicación llamando a Rapid

Usa **Basic Auth** con `client_id` como usuario y `client_secret` como contraseña.

```
Authorization: Basic base64(client_id:client_secret)
```

Endpoints que usan este método:
- [API de Transacciones](https://doc.rapidchargeback.com/es/canais/transactions/visao-geral/): crear, consultar, actualizar y eliminar transacciones
- [Merchants](https://doc.rapidchargeback.com/es/canais/merchants/listar-merchants/): listar los merchants de la empresa
- [Consulta de alertas](https://doc.rapidchargeback.com/es/callback/consultar-alertas/) y [callback de estado](https://doc.rapidchargeback.com/es/callback/atualizar-status/)
- [API de Evidencias](https://doc.rapidchargeback.com/es/canais/evidence/visao-geral/) y captura del lado del servidor (producto Disputa)

### Credenciales

| Credencial | Descripción |
|---|---|
| `client_id` | ID de tu empresa (generado en el panel) |
| `client_secret` | Clave secreta (generada en el panel, trátala como una contraseña) |

### Ejemplo de header

```
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
```

Donde el valor base64 se decodifica como `client_id:client_secret`.

### Seguridad

- Usa siempre HTTPS
- No incluyas el `client_secret` en código frontend, repositorios públicos ni logs
- Rota el `client_secret` si sospechas que se expuso; las credenciales nuevas se generan en el panel

---

## Rapid llamando a tu aplicación (webhook)

En el formato `v2`, Rapid firma cada webhook con **HMAC-SHA256** y envía la firma y el timestamp en los headers:

```
X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp: 1790000000
```

El contenido firmado **no es solo el cuerpo**: es `${X-Webhook-Timestamp}.${cuerpo_crudo}`, el timestamp, un punto y el cuerpo exactamente como llegó. Calcular el HMAC solo sobre el cuerpo da un valor distinto y toda solicitud se rechaza. El timestamp entra en el cálculo para impedir que un POST capturado se reenvíe después (rechaza los que estén fuera de una ventana de 5 minutos).

La clave de firma (`secret`) la **genera Rapid** cuando registras el webhook y aparece **una sola vez** en el panel, en **Configuración › Webhook**. No la eliges tú y no hay forma de consultarla después: si la pierdes, genera otra en **Configuración › API** (la anterior deja de valer al instante).

El paso a paso de la validación, con ejemplos en Node.js, Python y PHP, está en [Autenticación del webhook](https://doc.rapidchargeback.com/es/canais/webhook/autenticacao/).

### Formato `legacy`

Las cuentas migradas del sistema anterior reciben los webhooks en el formato `legacy`, que **no está firmado**. En él, la autenticación son los headers que el sistema antiguo ya enviaba:

```
clientid: <client_id>
clientkey: <client_secret>
```

Estos dos headers existen **solo en `legacy`**. En `v2` no se envían: `clientkey` es tu credencial de acceso a la API, y enviarla en cada entrega la expondría en tu endpoint y en tus logs sin necesidad, ya que en `v2` la autenticación la hace la firma. Para saber en qué formato está tu cuenta, ver [Payload](https://doc.rapidchargeback.com/es/canais/webhook/payload/#formato-legacy).