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 is the API key.

1. Generate an API Key

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

2. Configure the 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 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

   You can rotate the secrets associated with an API key. Only the Signature Secret changes; the API Key stays the same.

---

Request Signing

Each request must be signed using HMAC-SHA256 with a timestamp. X-Timestamp is epoch milliseconds from Date.now(), and requests are accepted only within a 5-minute window. For a request with no body, such as a GET, the signed string is just the timestamp.

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");
}

Signing a request with no body

A GET carries no body, so you sign the timestamp on its own. Send it in the X-Timestamp header alongside the resulting X-Signature.

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());

Signing a request with a body

A POST sends a JSON body, so you sign the timestamp and the body together. Set Content-Type: application/json and send the same body you signed.

import fetch from "node-fetch";

const apiKey = "YOUR_API_KEY";
const signatureSecret = "YOUR_SIGNATURE_SECRET";
const body = JSON.stringify({
  users: [{ contact: "[phone]" }],
  securityLevel: "CONTACT",
  credentials: [{ type: "JSON", name: "Welcome Pack" }],
});

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());