# HMACSHA256 Auth

Authentication for iyzico services aligns with Basic Auth principles, while enhancing security through a precise sequence of encryption techniques, including PKI string, Base64, HMAC and SHA-256 hashing

To access our API securely, authentication is required. Authentication is achieved through the inclusion of an `API Key` and `base64EncodedAuthorization` together in the header of your HTTP requests.

```http
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
```

**Example Request Header:**

```http
POST /payment/bin/check HTTP/1.1
Host: sandbox-api.iyzipay.com
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtbDlNZDFHajNJWWNtdTROZGFXeGFTVW9Db1g3REM1UkEmcmFuZG9tS2V5OjEyMzQ1Njc4OSZzaWduYXR1cmU6MDc5ZGY0YjI0MjZmYzdmNDIwOGQ4ZjIyZmJjMDM0OTc5NDAxOWY4Y2UyYjA3MTFkZTc4MDhiNDg3NGY0ZTc5Ng==
Content-Type: application/json
x-iyzi-rnd: 123456789 // x-iyzi-rnd used to be random key from previous SHA1 Authentication
```

## **Overview**

Here's a breakdown of the required components:

* **apiKey**: Your unique API key assigned to your account.
* **secretKey**: Your secret key associated with your account.
* **x-iyzi-rnd**: A randomly generated number by merchants that included in the request header for each API call. (x-iyzi-rnd used to be random key from previous SHA1 Authentication)
* **encryptedData:** The encrypted version of the request payload parameters with HMACSHA256.

Authentication can be divided into three sequential steps:

1. encryptedData
2. base64Encoded
3. Authorization

### 1. **encryptedData**

The `encryptedData` represents a encrypted version of the request payload, the process entails generating a hash using HMACSHA256 encryption.

The signature is generated using the following formula, relatively;

```
HMACSHA256(randomKey + uri.path + request.body, secretKey)
```

{% hint style="info" %}
**`randomKey`**`;` 

* could be either x-iyzi-rnd used to be random key from previous SHA1 Authentication.
* Or please do not hesitate generate randomly.
  {% endhint %}

With in a sample, below you may find a dummy [Bin Check](https://docs.iyzico.com/v/en/advanced/installment-and-bin-service#bin-service-request-1) request curl;

```
curl 
--location --request POST 'https://api.iyzipay.com/payment/bin/check' \
--header 'Authorization: IYZWSv2 ***' \
--header 'x-iyzi-rnd: 123456789' \ 
--header 'Content-Type: application/json' \
--data-raw '{
    "locale":"tr",
    "binNumber":"535805",
    "conversationId": "docsTest-v1"
}'
```

`encryptedData` for that Bin Check request above is;

```
079df4b2426fc7f4208d8f22fbc0349794019f8ce2b0711de7808b4874f4e796
```

### 2. base64Encoded

Assuming that the `encryptedData` has been generated correctly, it is now time for Base64 encryption. 

The signature is generated using the following formula, relatively;

```plaintext
base64("apiKey:"+apiKey+"&randomKey:"+randomKey+"&signature:"+encryptedData)
```

The result is our `base64EncodedAuthorization` to be used in the header.

### 3. Authorization

After all the operations, the final and simplest step is to include `IYZWSv2`, `base64EncodedAuthorization` in the header, relatively.

```
...
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
...
```

{% hint style="warning" %}
In between IYZWSv2 and base64EncodedAuthorization there is a single line space.
{% endhint %}

## Sample Pre-request Script of Authorization on Postman

Taking a dummy Bin Check request as an example, the authorization process would be as follows;

```javascript
var apiKey = environment.apiKey;
var secretKey = environment.secretKey;
 
//Generate authorization string
function generateAuthorizationString() {

    // Lets create uniq randomKey
    // Sample randomKey : 1722246017090123456789
    // x-iyzi-rnd used to be random key from previous SHA1 Authentication, so plese do not hesitate to use x-iyzi-rnd as your randomkey.
    var randomKey = new Date().getTime() + "123456789";
    
    // Get the uri path for this request
    // Sample uri_path : /payment/bin/check
    var uri_path = "/payment/bin/check";
    
    // Get the payload and concatanete with uri path and randomKey.
    // Sample payload : payload: 1722246017090123456789/payment/bin/check{"binNumber":"589004"}
    var payload = _.isEmpty(request.data) ? randomKey + uri_path : randomKey + uri_path + request.data;
    
    // Encrypt the payload with HMACSHA256
    // Sample encryptedData : 91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9
    var encryptedData = CryptoJS.HmacSHA256(payload, secretKey);
 
    // Create the authorizationString using encryptedData
    /* Sample authorizationString : apiKey:sandbox-3uHv0LccjcWDyFHTvJpiACKPcJwbczmZ&
                                        randomKey:1722246017090123456789&
                                        signature:91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9 */
    var authorizationString = "apiKey:" + apiKey
                        + "&randomKey:" + randomKey
                        + "&signature:" + encryptedData;
    
 
    // Encode the authorizationString with base64 
    // Sample base64EncodedAuthorization : YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    var base64EncodedAuthorization = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(authorizationString));
 
    // Concatanate the encoded authorizationString with 'IYZWSv2 '.
    // Sample return value : IYZWSv2 YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    return "IYZWSv2 " + base64EncodedAuthorization;
}
var authorization = generateAuthorizationString();
postman.setEnvironmentVariable("authorization", authorization);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iyzico.com/en/getting-started/preliminaries/authentication/hmacsha256-auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.