Authorization & signature

When dealing with security, Icypeas has two methods:

1. Using only the API key to make requests. Ideal when using low-code platforms.
2. Using the API key & the secret to sign your requests. Ideal when more security is needed.

First method: using only the API key

When using low-code platforms, sometimes it is hard to compute a signature per request. Only using the API key is therefore the way to go.

tip

If you need more security, please see the next section which explains how to compute a signature that is verified for each request.

So you'll need to use the Authorization header in the following way:

• Authorization: MY_API_KEY.

You'll also need to specify the Content-Type header:

• Content-Type: application/json

And that's it. You can make your first request:

const myUrl = "URL_YOUR_TRYING_TO_REQUEST";
const res = fetch(myUrl, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization: "MY_API_KEY",
    },
    body: JSON.stringify({
          email: "test@icypeas.com",
    }),
});
res.then((v) => v.json()).then((data) => console.log(data));

Second method: Computing the signature with the secret

The security of the API is based on a HMAC-SHA1 signature and the use of a timestamp to avoid man in the middle attack to replay a previous request.

To do so, we ask our users to use two different headers:

• Authorization header composed of apiKey:signature.
• X-ROCK-TIMESTAMP header composed of the current time as an UTC ISO 8601 string (e.g: 2023-03-12T12:01:02.000Z).

Let's imagine that your API key is test-key and your secret is test-secret

To compute the signature you need to use this simple procedure:

1. Get the URL to which you are going to send a request, for instance: https://app.icypeas.com/api/a/actions/subscription-information.
2. Grab the endpoint (the path name): /api/a/actions/subscription-information
3. Grab the HTTP method (here it is a POST request)
4. Generate a UTC timestamp in ISO 8601 format.
5. Concatenate the method + the endpoint + the timestamp and lowercase your final string
6. Use the library in your language to create a HMAC-SHA1 signature of this payload using your secret.

Here you'll find the way to do it with NodeJS:

import { URL } from 'url';
import Crypto from 'crypto';

/**
 * Generate the signature for an API call
 * @param url - The api route you are going to send a request to
 * @param method - The HTTP method (GET, POST, PUT, DELETE)
 * @param secret - Your API secret
 * @param timestamp - A ISO 8601 UTC string (ex: 2023-03-01T04:40:20Z)
 */
const genSignature = (
    url: string,
    method: string,
    secret: string,
    timestamp: string = new Date().toISOString()
) => {
    const endpoint = new URL(url).pathname;
    const payload = `${method}${endpoint}${timestamp}`.toLowerCase();
    const sign = Crypto.createHmac("sha1", secret).update(payload).digest("hex");

    return { signature: sign, timestamp };
};

You can also find the way to do it in PHP, Python, Rust and Go directly from the API tab in your profile on Icypeas.

Then you can make your first request:

const myUrl = "URL_YOUR_TRYING_TO_REQUEST";
const { signature, timestamp } = genSignature(myUrl, "POST", "test-secret");
const res = fetch(myUrl, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization: `test-key:${signature}`,
        "X-ROCK-TIMESTAMP": timestamp,
    },
    body: JSON.stringify({
          email: "test@icypeas.com",
    }),
});
res.then((v) => v.json()).then((data) => console.log(data));