---
description: Use API keys to authenticate API requests.
---

# API keys

BanQ authenticates your API requests using your service's API keys.

* If a request doesn't include a signature, BanQ returns an URL signature error.
* If a request includes an invalid signature, BanQ returns a header signature error.

You can create API keys with the following instruction

## RSA-2048 key pair

### Create key pair

Create [RSA-2048](https://en.wikipedia.org/wiki/RSA_numbers#RSA-2048) key pair for your service.

```bash
mkdir pk
openssl genrsa -out pk/gen.private.key 2048
openssl rsa -in pk/gen.private.key \
	-outform PEM -pubout -out pk/gen.public.pem
```

### Usage

<table data-full-width="false"><thead><tr><th width="116">Type</th><th width="179">File</th><th>When to use</th><th data-hidden>When to use</th><th data-hidden>File</th></tr></thead><tbody><tr><td>Private</td><td>pk/gen.private.key</td><td><strong>On the server side</strong>: Use this key to authenticate your API request.<br><strong>Don't expose this key.</strong></td><td><p><strong>On the server side</strong>: Use this key to authenticate your API request to other service.</p><p><strong>Don't expose this key</strong>.</p></td><td>pk/gen.private.key</td></tr><tr><td>Public</td><td>pk/gen.public.pem</td><td>Provide this key for other service to verify API request (signed with the private key).<br><strong>Can be publicly accessible.</strong></td><td>Provide this key for other service to verify your API request (signed by the private key).<br><strong>Can be publicly accessible.</strong></td><td>pk/gen.public.pem</td></tr></tbody></table>

## Authenticate API request

### Using Shell Command

1.  Generate signature of the message with your key

    ```bash
    openssl dgst -sha256 -sign pk/gen.private.key msg > sig
    ```
2.  Fill base64 encoded signature in request header as `X-Signature`

    ```bash
    cat sig | base64
    ```

### Using JavaScript

```javascript
function sign(privatekey, msg) {
    var rsa = new RSAKey();
    rsa.readPrivateKeyFromPEMString(privatekey);
    let hSig = rsa.sign(msg, "sha256");
    let b64 = btoa(hSig.match(/\w{2}/g).map(function (a) { return String.fromCharCode(parseInt(a, 16)); }).join(""))
    return b64
}
```

## Verify API request

1.  base64 decode the signature from request header

    ```bash
    echo BASE64_ENCODED_SIG | base64 -d > sig
    ```
2.  Verify signature

    ```bash
    openssl dgst -sha256 -verify pk/gen.public.pem -signature sig msg
    ```
