# Authorization

In order to authorize your requests, get a [private key](https://docs.0xpay.app/integration-cookbook/getting-started/merchant-setup#api-keys).

Authorization is required:

* To verify your request and prove your ownership of the merchant.
* To verify notifications (webhooks) that 0xpay sending to your server to verify the authority.

### Building the signature

General formula is: 

`signature = hmacsha256(method + url + body + timestamp, privateKey)`

Overall guide to build your signature is described below: 

1. Concatenate HTTP method(`POST`, `GET`, etc), URL path, request body (or an empty string, if the body is empty), and timestamp in seconds. Let's call resulted string `<MESSAGE>`
2. Sign received `<MESSAGE>` using [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) algorithm with merchant's `<PRIVATE_KEY>`. Let's call resulted hash `<SIGNATURE>`

### Signing a request

To make a valid request, you have to include several headers along with it:

| Header        | Value                                                               |
| ------------- | ------------------------------------------------------------------- |
| `merchant-id` | Copy it from your 0xpay **Dashboard -> Merchant Settings** section. |
| `signature`   | `<SIGNATURE>`                                                       |
| `timestamp`   | `<TIMESTAMP>`                                                       |

For example, I want to create an address in the BITCOIN network. I have to `POST /merchants/addresses` the API endpoint. Here is my payload:

```
{
  "meta":  "<my-user-id>",
  "blockchain":  "BITCOIN"
}
```

Let's say, that my current timestamp is `1650289480` (in seconds!!!). Lets concatenate parts of our request and we will receive next `<MESSAGE>`:

```
POST/merchants/addresses{
  "meta": "<my-user-id>",
  "blockchain": "BITCOIN"
}1650289480
```

Then, I will receive `<SIGNATURE>` using [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) with the `private key`.

As far as we already generated `<SIGNATURE>`, we can make a request.&#x20;

#### Code examples:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const merchantId = 'b2a46898-7e6d-4c13-8a31-47154c43ee8b'
const key = "bd4c0f27382cbdf0c52318a99308fc6d"
const timestamp = Math.floor(Date.now() / 1000)
const path = ('your-path-to-method')
const sign = CryptoJS.HmacSHA256(request.method + path + request.body + timestamp, key).toString()
```

{% endtab %}
{% endtabs %}

### Verifying a notification (webhook)

Let's assume that you receive some replenishment webhook sent from 0xpay server, that is directed to some  `domain.com/webhooks/0xpay` endpoint you have specified earlier in the [merchant's settings](https://docs.0xpay.app/integration-cookbook/getting-started/merchant-setup#notifications).

Body of the webhook is:

```
{
  "id": "some-id",
  "from": "some-address",
  "ticker": "BTC",
  "blockchain": "BITCOIN",
  "kind": "Replenish",
  "block": "1000",
  "status": "Confirmed",
  "time": 123123123
}
```

Header of the request:

```
SIGNATURE: some-random-signature
TIMESTAMP: 1652887112
```

So then build the \<MESSAGE> mentioned [above](#building-the-signature)

```
POSTdomain.com/webhooks/0xpay{
  "id": "some-id",
  "from": "some-address",
  "ticker": "BTC",
  "blockchain": "BITCOIN",
  "kind": "Replenish",
  "block": "1000",
  "status": "Confirmed",
  "time": 123123123
}1652887112
```

Now you can generate the signature using the formula mentioned above and compare it with the `SIGNATURE` we sent you in headers. If signatures match, then the request is original.

### Signature Examples

Let's build exemplary signatures for each of our requests in order to demonstrate the logic behind this process. In this case, we can equal values for&#x20;