Skip to main content

​
🔑 API Key

The Humanos API uses multiple layers of authentication and request validation. The first being the API key.

​
1. Generate an API Key

Navigate to the Humanos Dashboard click API keys on the sidebar and create a new key.

​
2. Configure API Key

  • Name (required) – A label to identify the API key.
  • Description (optional) – A short note to document the purpose of the API key.
  • Expiration (days) (optional) – The number of days until the key expires.

​
3. Retrieve Your Credentials

Once the API key is created, copy and securely store the following values:
  • API Key
  • Signature Secret

​
4. Rotate Secrets

It is possible to rotate the secrets associated with an API key.
Only the Signature Secret changes; the API Key remains the same.

​
🔒 Request Signing

Each request must be signed using HMAC-SHA256 with a timestamp.

​
Signature Generation Example

import crypto from "crypto";

function generateSignature(data, secret, timestamp) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(data ? `${timestamp}.${data}` : timestamp.toString());
  return hmac.digest("hex");
}

​
Example: GET Request (no body)

import fetch from "node-fetch";

const apiKey = "YOUR_API_KEY";
const signatureSecret = "YOUR_SIGNATURE_SECRET";
const timestamp = Date.now();
const signature = generateSignature("", signatureSecret, timestamp);

const response = await fetch("https://api.humanos.id/v0/processes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "X-Timestamp": timestamp.toString(),
    "X-Signature": signature,
  },
});
console.log(await response.json());

​
Example: POST Request (with body)

import fetch from "node-fetch";

const apiKey = "YOUR_API_KEY";
const signatureSecret = "YOUR_SIGNATURE_SECRET";
const body = JSON.stringify({
  contacts: ["+351912345678"],
  processIds: ["64c8e5f7d5a4f9123b7c9a1e"],
});

const timestamp = Date.now();
const signature = generateSignature(body, signatureSecret, timestamp);

const response = await fetch("https://api.humanos.id/v0/process/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "X-Timestamp": timestamp.toString(),
    "X-Signature": signature,
  },
  body,
});
console.log(await response.json());