Authentication
This page is the technical reference for every Rapid authentication mechanism.
Your application calling Rapid
Section titled “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: create, get and update transactions
- Merchants: list, get, create or update (one by one or in batches), edit and delete the company’s merchants
- Enrollments: request (one by one or in batches), list, get and request deactivation
- Usage by merchant: billable alerts per merchant in the cycle
- List alerts and status callback
- Evidence API and server-side capture (Dispute product)
Credentials
Section titled “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
Section titled “Header example”Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=Where the base64 value decodes to client_id:client_secret.
Security
Section titled “Security”- Always use HTTPS
- Do not include
client_secretin frontend code, public repositories or logs - If you suspect it was exposed, generate a new
client_secretand revoke the previous one right away (see below)
Rotating the client_secret
Section titled “Rotating the client_secret”Generate a new secret under Settings › API. The client_id stays the same. The previous secret keeps working for 24 hours from the rotation, and the dashboard shows until when. During that window Rapid accepts both, so you can update one system at a time without downtime:
- Generate the new secret in the dashboard and store it in your secrets vault (it is shown only once).
- Update each system that calls the API.
- Done: the previous one stops on its own at the end of the 24 hours. If you rotated because of a leak, do not wait: click Revoke the previous key now and it stops working immediately.
Generating another secret within the 24 hours discards the previous one: only the secret that was valid until that second rotation keeps working, alongside the new one.
Rapid calling your application (webhook)
Section titled “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: 1790000000The 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.
legacy format
Section titled “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. After a client_secret rotation, the clientkey of the deliveries already carries the new secret.