## Overview

Reservepay uses two different authentication methods depending on where the request is coming from: your backend server or your frontend application (browser or mobile app).

## Account access

Send Reservepay the email address that should have Merchant Dashboard access. Reservepay sends an invitation so you can configure API keys, SDK installations, and webhooks. Sign in to the [Merchant Dashboard](https://dashboard.reservepay.com/sign-in).

## Test mode and live mode

Test and live are **separate merchant accounts**, and you switch between them in the dashboard. Each account has its own API keys, SDK installations, and webhook endpoints. An API key belongs to exactly one account, so the key you send decides whether a request is a test or a live one.

* **API host:** Both accounts use `https://api.reservepay.com`.
* **Webhooks:** Point the test account's endpoints at your development URLs and the live account's endpoints at your production URLs.

Build and test everything on the test account first. Test payments use generated [test cards](/tools/test-card-generator) and never move real money. When you go live, repeat the setup on the live account: create API keys, SDK installations, and webhook endpoints there, and update your configuration.

## Backend authentication

For server-to-server communication, Reservepay uses **API keys**. These keys grant full access to your merchant account's sensitive operations, such as initiating payments, searching for transactions, or managing refunds.

### API keys

You can manage your API keys in your merchant dashboard.

* You can create multiple API keys. We recommend creating a unique key for each of your applications or services. This allows you to rotate or revoke keys independently without affecting your entire infrastructure.

* To rotate a key, generate a new API key, update your application, verify that the new key works, then revoke the old one. Two keys can be valid at the same time during that window.

* Your API keys are secret. They must **never** be exposed in frontend code, mobile apps, or public repositories.

* API keys aren't tied to IP addresses. Anyone who has a key can use it, so store keys as carefully as passwords.

### API version

Send `Api-Version: 2025-04-01` as a header on every backend request. Keep the version out of the URL.

### Authenticating requests

To authenticate a backend request, include your API key in the `Authorization` header as a `Bearer` token.

#### Example

```bash
curl -X POST https://api.reservepay.com/merchants/initiate-payment-flow \
  -H "Authorization: Bearer reservepay_x8R..." \
  -H "Api-Version: 2025-04-01" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ ... }'
```

### Webhook signing keys

Each webhook endpoint has its own `verification_key`. To rotate it, see [Rotating the signing key](/guides/real-time-notifications#rotating-the-signing-key).

## Frontend authentication

Authentication in the frontend (web browsers and mobile applications) is handled via a combination of your **Merchant ID** and an **Installation ID**. This approach is designed to be safe for public exposure while maintaining strict security controls. iOS and Android use those same public identifiers. Keep secret API keys on the backend.

### SDK installations

An SDK installation represents a specific instance of your application where the Reservepay SDK is deployed. You can create and manage these in your merchant dashboard.

When you create an installation, you must define:

* **Platform:** The type of environment (e.g., Web, iOS, Android).
* **Identifier:** To prevent unauthorized use, each installation is bound to its environment:
  * **Web:** Must include the allowed domain names.
  * **Mobile:** Must include the Bundle ID (iOS) or Package Name (Android).
* **Payment methods:** You can specify which payment methods are available for a particular installation.
* **Customer data:** Define which customer information (e.g., email, phone number) must be captured during the checkout process.

The SDK checks these constraints at runtime to ensure the request is originating from a legitimate environment.

### Initializing the SDK

To authenticate frontend requests, provide your `merchantId` and `installationId` when initializing the SDK.

#### Example

```ts
const reservepay = window.Reservepay.initReservepay({
  merchantId: "123456789100",
  installationId: "ins_123",
})
```

## Best practices

* Do not hardcode secret API keys in your source code. Use environment variables or a secure secret management system.

* Never use backend API keys in your frontend or mobile app. If an API key is leaked, revoke it immediately in the dashboard and generate a new one.

* Create a separate SDK installation for each website or mobile app. This allows you to tailor the payment experience and security settings for each platform.

* Always provide the most specific domain names or bundle IDs possible for your SDK installations to minimize the risk of unauthorized use.