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

# Authentication

> Authenticate every API request with your Revtain API key.

Pass your API key via the `X-API-KEY` header on all requests:

```bash theme={null}
X-API-KEY: rev_dTviCg52T8gLPCjrrW4KA0NKf_f5pQgk
```

<Warning>
  **Keep this secret.** Your API key can trigger charges. Never expose it in client-side code, public repos, or logs.
</Warning>

## Onboarding Credentials

Revtain provisions your account and issues your credentials — typically the same business day. You receive three:

| Credential                 | Format                            | Purpose                                                                                                                              |
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **API Key** (secret)       | `rev_xxxxxxxxxxxxxxxxxxxxxxxx`    | Authenticates all API requests. Can trigger charges — keep it server-side only.                                                      |
| **Publishable Key**        | `rev_pk_xxxxxxxxxxxxxxxxxxxxxxxx` | Read-only key, safe to embed in client-side code. Used by the [in-app payment wall](/guides/in-app-paywall). Cannot trigger charges. |
| **Webhook Signing Secret** | `whsec_xxxxxxxxxxxxxxxxxxxxxxxx`  | Verifies inbound webhook signatures                                                                                                  |

<Note>
  The API key and webhook signing secret are sensitive — store them in environment variables, never in client-side code or repositories. The publishable key is designed to be public and is the only credential safe to ship in a browser.
</Note>

## What You Provide

* Your **payment gateway key** (Stripe secret key, Checkout.com secret key, etc.)
* A **webhook URL** (HTTPS endpoint to receive recovery notifications)

## Optional Configuration

| Field              | Type           | Default       | Description                                                                                                                                                                                                                                                                                                 |
| ------------------ | -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `billingCycleDay`  | integer (1-31) | auto-detected | Day of month customers are billed. Optimises retry timing. If you don't set it, Revtain infers it automatically from your first renewal failure — no action needed.                                                                                                                                         |
| `timezone`         | string         | `UTC`         | IANA timezone (e.g., `America/New_York`).                                                                                                                                                                                                                                                                   |
| `dunningEnabled`   | boolean        | `true`        | When `true`, Revtain sends a `recovery.failed` webhook to your endpoint after all retry strategies are exhausted. When `false`, no webhook is fired on failure — only `recovery.success` and `recovery.blocked` fire. Keep this `true` unless you are handling failure detection entirely on your own side. |
| `cardUpdateDomain` | string         | —             | Custom domain for branded card update page (e.g., `pay.yourdomain.com`).                                                                                                                                                                                                                                    |

## Rate Limits

| Endpoint                       | Limit                                |
| ------------------------------ | ------------------------------------ |
| `/api/recovery/execute`        | 60 requests / minute / API key       |
| `/api/recovery/paywall-status` | 120 requests / minute / key          |
| All others                     | No specific limit (fair-use applies) |

Rate-limited requests return `429 Too Many Requests` with a `retryAfter` field.