> For the complete documentation index, see [llms.txt](https://alpha-carbon.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alpha-carbon.gitbook.io/docs/banq/api-keys.md).

# 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
   ```