## 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).

## 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.

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

### 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 "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ ... }'
```

## 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.

### 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 will 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. 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.