> For the complete documentation index, see [llms.txt](https://developers.coindirect.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coindirect.com/guides/api-authentication.md).

# API Authentication

While some endpoints are public and require no authentication, most interaction with the Coindirect API requires it.

## **How To Authenticate**

In order to authenticate with the Coindirect API, you need to create a HAWK AUTH ID and HAWK AUTH KEY pair on your Coindirect account. You can do this by navigating to the Settings -> API Keys page. Once you have these, you may then proceed to integrate using the Holder-of-Key Authentication Scheme otherwise known as HAWK.

## **HAWK Authentication**

It is best to read the guides available on the [HAWK readme](https://github.com/mozilla/hawk/blob/main/README.md). The Coindirect API makes use of SHA256 for calculating the HMAC.

HAWK optionally supports payload validation (POST/PUT data payload) as well as response payload validation, these are not enabled on the Coindirect API so can be ignored.

## Hints

{% hint style="info" %}
**Do not** include your **request body** in your string to sign when calculating the HAWK signature
{% endhint %}

{% hint style="info" %}
**Do not** include **query parameters** of your request in your string to sign when calculating the HAWK signature
{% endhint %}

{% hint style="info" %}
**Make sure** that your **nonce** value is unique for each of your requests. Otherwise you get a 429 error
{% endhint %}

## Example

Here's a piece of code in PHP that can give you an idea on how to buld your signature.

```php
<?php
function generateSignature($string, $key) {
    return base64_encode(
        hash_hmac(
            "sha256",
            $string,
            $key,
            true
        )
    );
}
​
$hawkHeader = "hawk.1.header"."\n";
$hawkHeader .= "1653303875";
$hawkHeader .= "\n";
$hawkHeader .= "VIp7ugfn";
$hawkHeader .= "\n";
$hawkHeader .= "GET";
$hawkHeader .= "\n";
$hawkHeader .= "/api/currency/fiat";
$hawkHeader .= "\n";
$hawkHeader .= "api.sandbox.coindirect.com";
$hawkHeader .= "\n";
$hawkHeader .= "443";
$hawkHeader .= "\n";
$hawkHeader .= "\n";
$hawkHeader .= "\n";
​
$authKey = "XVNjIiG8ePzqCsQ20qk0ChIvQJpG7S0GQq5MSkEhTdSBxGMmoI82S4n0O188F9Eo";
​
echo generateSignature($hawkHeader, $authKey);
```

The above code calculates the following signature:

```
zVUmLFKdBZywyl8ALX9Aye2bnC7AIQwxsBllXVa1LdI=
```

## Some code lines

{% tabs %}
{% tab title="Header Creation Example (Java)" %}

```java
    private String getAuthorizationHeader(String requestUrl, String method, byte[] body, CoinDirectProps coinDirectProps) throws IOException, URISyntaxException {
        // method can be POST, GET, DELETE, PUT
        // time must be accurate
        long timestamp = Math.round(System.currentTimeMillis() / 1000);
        // this is a random unique string (duplicates within 15 minutes will be rejected)
        String nonce = UUID.randomUUID().toString().substring(0, 8);

        URI uri = new URI(requestUrl);
        String host = uri.getHost();
        String path = uri.getPath(); // eg: /api/v1/pay
        String query = uri.getRawQuery(); // x=y
        int port = uri.getPort() == -1 ? 443 : uri.getPort(); // Port 443 default for HTTPS
        StringBuilder hawkHeader = new StringBuilder();
        hawkHeader.append("hawk.1.header\n");
        hawkHeader.append(timestamp);
        hawkHeader.append("\n");
        hawkHeader.append(nonce);
        hawkHeader.append("\n");
        hawkHeader.append(method.toUpperCase());
        hawkHeader.append("\n");
        hawkHeader.append(path);
        if (query != null) {
            hawkHeader.append("?");
            hawkHeader.append(query);
        }
        hawkHeader.append("\n");
        hawkHeader.append(host);
        hawkHeader.append("\n");
        hawkHeader.append(port);
        hawkHeader.append("\n");
        // body (not used)
        hawkHeader.append("\n");
        // app data (not used)
        hawkHeader.append("\n");
        try {
            String mac = generateHash(coinDirectProps.getAuthKey(), hawkHeader.toString());
            return "Hawk id=\"" + coinDirectProps.getAuthId() + "\", ts=\"" + timestamp + "\", nonce=\"" + nonce + "\", mac=\"" + mac + "\"";
        } catch (Exception e) {
            throw new IOException(e);
        }
    }
```

{% endtab %}

{% tab title="HAWK Header Hash Example (Java)" %}

```java
private String generateHash(String key, String data) throws InvalidKeyException, NoSuchAlgorithmException {
    Mac sha256_HMAC = null;
    String result = null;
    byte[] byteKey = key.getBytes(StandardCharsets.UTF_8);

    final String HMAC_SHA256 = "HmacSHA256";
    sha256_HMAC = Mac.getInstance(HMAC_SHA256);

    SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA256);
    sha256_HMAC.init(keySpec);
    byte[] mac_data = sha256_HMAC.doFinal(data.getBytes());

    return Base64.getEncoder().encodeToString(mac_data);
}
```

{% endtab %}
{% endtabs %}