# Authentication

> Technical reference for every Rapid authentication mechanism: Basic Auth for your calls and the webhook signature for Rapid's calls.

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

This page is the technical reference for every Rapid authentication mechanism.

## Your application calling Rapid

Use **Basic Auth** with `client_id` as the username and `client_secret` as the password.

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

Endpoints that use this method:
- [Transactions API](https://doc.rapidchargeback.com/en/canais/transactions/visao-geral/): create, get, update and delete transactions
- [Merchants](https://doc.rapidchargeback.com/en/canais/merchants/listar-merchants/): list the company's merchants
- [List alerts](https://doc.rapidchargeback.com/en/callback/consultar-alertas/) and [status callback](https://doc.rapidchargeback.com/en/callback/atualizar-status/)
- [Evidence API](https://doc.rapidchargeback.com/en/canais/evidence/visao-geral/) and server-side capture (Dispute product)

### Credentials

| Credential | Description |
|---|---|
| `client_id` | Your company's ID (generated in the dashboard) |
| `client_secret` | Secret key (generated in the dashboard, treat it as a password) |

### Header example

```
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
```

Where the base64 value decodes to `client_id:client_secret`.

### Security

- Always use HTTPS
- Do not include `client_secret` in frontend code, public repositories or logs
- Rotate the `client_secret` if you suspect it was exposed; new credentials are generated in the dashboard

---

## Rapid calling your application (webhook)

In the `v2` format Rapid signs each webhook with **HMAC-SHA256** and sends the signature and the timestamp in the headers:

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

The signed content is **not just the body**: it is `${X-Webhook-Timestamp}.${raw_body}`, the timestamp, a dot and the body exactly as it arrived. Computing the HMAC over the body alone gives a different value and every request is rejected. The timestamp is part of the calculation to prevent a captured POST from being replayed later (reject those outside a 5-minute window).

The signing key (`secret`) is **generated by Rapid** when you register the webhook and appears **only once** in the dashboard, under **Settings › Webhook**. You do not choose it and there is no way to look it up later: if you lose it, generate another under **Settings › API** (the previous one stops working immediately).

The validation step by step, with examples in Node.js, Python and PHP, is in [Webhook authentication](https://doc.rapidchargeback.com/en/canais/webhook/autenticacao/).

### `legacy` format

Accounts migrated from the previous system receive webhooks in the `legacy` format, which is **not signed**. In it, authentication is done by the headers the old system already sent:

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

These two headers exist **only in `legacy`**. They are not sent in `v2`: `clientkey` is your API access credential, and sending it with every delivery would expose it on your endpoint and in your logs for no reason, since in `v2` the signature does the authentication. To find out which format your account uses, see [Payload](https://doc.rapidchargeback.com/en/canais/webhook/payload/#legacy-format).