# Authorization

In order to authorize your requests, get a [private key](/integration-cookbook/getting-started/merchant-setup.md#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](/integration-cookbook/getting-started/merchant-setup.md#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;


---

# 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.0xpay.app/public-api/authorization.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.