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. 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

Do not include your request body in your string to sign when calculating the HAWK signature

Do not include query parameters of your request in your string to sign when calculating the HAWK signature

Make sure that your nonce value is unique for each of your requests. Otherwise you get a 429 error

Example

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

<?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

Header Creation Example (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);
        }
    }

HAWK Header Hash Example (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);
}