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

# Authentication

> Preview changes locally to update your docs

### Authentication with Omnispay

To get authenticated and start making API calls, you'll first need to retrieve your **API key** from the Omnispay dashboard.

**Prerequisite**: Generate an API Key

Before making API requests, the merchant must generate an API key by sending a request to the API. The response will contain the API key details, which should be used to authenticate subsequent requests.

#### Step 1: Retrieve your API Key

To obtain your API key:

1. **Log in** to your Omnispay dashboard.
2. Navigate to the **Developer Page**.
3. **Copy your API Key** from the page.

#### Step 2: API Key Validation

Before making any request, the client must include an API key in the request header. Upon receiving the request, the backend will perform the following:

1. **Check the API Key**:
   * First check if the request contains a valid API key in the header.
   * Verify whether the API key has the proper access to the requested endpoints.
   * Check if the request originates from an IP address that has been granted permission for that API key.
   * If all these validations pass, the user can access the requested resources.
   * If the URL or IP does not have the necessary permissions, the user can update their allowed endpoints and IP addresses against the API key.
   * If the API key is missing, the request will be rejected with a proper error message.

***

## Step 3: HMAC Authentication Using Secret Key

After validating the API key, Omnispay provides a **secret key** to each merchant during API key creation. This key must be used for HMAC-based authentication.

### 🔐 How HMAC Works

**HMAC (Hash-based Message Authentication Code)** ensures that the message is:

* **Authentic** (sent by a trusted party),
* **Untampered** (not altered in transit).

You generate an HMAC by hashing the payload or message (e.g., request body or query) using your **secret key** and a cryptographic algorithm like HmacSHA256. The server then verifies this signature using the stored secret key.

> 💡 The `secretKey` is issued securely by Omnispay Admin when the API key is created. This must be stored securely and never exposed publicly.

### 🔗 External References

* [RFC 2104 – HMAC: Keyed-Hashing for Message Authentication](https://en.wikipedia.org/wiki/HMAC)\
  *The original HMAC specification from the Internet, along with explanations, examples, and use cases. This reference provides a comprehensive understanding of how HMAC ensures data integrity and authenticity using a shared secret key.*

### ✅ Sample HMAC Validation Code (Java)

```java theme={null}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class HmacUtil {
    /**
     * Generates a Base64-encoded HMAC SHA-256 for the given data using the provided secret key.
     */
    public static String generateHmac(String data, String secretKey) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hmacBytes);
        } catch (Exception e) {
            // Log exception as per your application's logging strategy
            e.printStackTrace();
            return null;
        }
    }
}

```

**Please note:** All connections to the API are server-to-server. Access is permitted only from authenticated sources or explicitly whitelisted IP addresses.