Authentication

Learn how to authenticate with the Humanos API using API keys and request signing

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.tech/request", {
  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: ["[phone]"],
  processIds: ["64c8e5f7d5a4f9123b7c9a1e"],
});

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

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