​
API keys

Hilt API keys are for server-side merchant integrations. They let a merchant’s own backend, bot, or automation call the public Hilt contract directly from server-side code.

​
Create a key from the dashboard

The recommended path is:
  1. sign in to the merchant dashboard
  2. open Advanced
  3. create a key in the key manager
  4. copy the raw key immediately
  5. store it in your secret manager
The raw key is shown once.

​
How to send the key

Send the key in the request header: 
X-Hilt-Key: hk_live_...

​
What API keys should call

Use API keys for:
  • products
  • hosted checkout helpers
  • payment status
  • memberships
  • receipts
  • support automation

​
Use API keys only on your backend

Do not:
  • embed a key in browser code
  • ship it inside a mobile app
  • expose it in a public checkout page
  • hand it to third-party scripts
StepGood practice
CreateName the key for the system that will use it
StorePut it in a secret manager immediately
UseRestrict it to backend or bot-side code
ReviewCheck when it was last used and whether it is still needed
RevokeRemove it when the integration is replaced or retired

​
A production-friendly key setup

Most teams end up with at least two keys:
  • one key for the live backend or bot
  • one key for support scripts or low-risk maintenance tasks
That gives you cleaner audit trails and makes rotation much safer than sharing one key across every workflow.

​
Rotation playbook

When you need to rotate a key:
  1. create the replacement key in the dashboard
  2. store it in your secret manager
  3. deploy the new value to the system that uses it
  4. make one read call such as GET /v1/products to confirm it works
  5. revoke the old key
That avoids the common failure mode of revoking first and breaking a live bot or backend job.

​
Naming pattern that works well

Good names tell the merchant what the key is for:
  • Production Telegram bot
  • Discord checkout integration
  • Warehouse fulfilment sync
  • Launch-week support script

​
First request examples

​
cURL

curl https://api.hilt.so/v1/products \
  -H "X-Hilt-Key: hk_live_..."

​
TypeScript

const response = await fetch("https://api.hilt.so/v1/products", {
  headers: {
    "X-Hilt-Key": process.env.HILT_API_KEY!,
  },
});

if (!response.ok) {
  throw new Error(`Hilt request failed: ${response.status}`);
}

const products = await response.json();

​
Python

import requests

response = requests.get(
    "https://api.hilt.so/v1/products",
    headers={"X-Hilt-Key": "hk_live_..."},
    timeout=20,
)
response.raise_for_status()
print(response.json())

​
A small server wrapper that scales well

If your backend will make more than a few Hilt calls, centralise the header handling instead of repeating it in every request.

​
TypeScript

const HILT_API_URL = process.env.HILT_API_URL ?? "https://api.hilt.so";
const HILT_API_KEY = process.env.HILT_API_KEY!;

async function hilt<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(`${HILT_API_URL}${path}`, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      "X-Hilt-Key": HILT_API_KEY,
      ...(init.headers ?? {}),
    },
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail ?? `Hilt request failed: ${response.status}`);
  }

  return response.json() as Promise<T>;
}

​
Python

import os
import requests

HILT_API_URL = os.getenv("HILT_API_URL", "https://api.hilt.so")
HILT_API_KEY = os.environ["HILT_API_KEY"]

session = requests.Session()
session.headers.update({"X-Hilt-Key": HILT_API_KEY})

def hilt_get(path: str, **kwargs):
    response = session.get(f"{HILT_API_URL}{path}", timeout=20, **kwargs)
    response.raise_for_status()
    return response.json()
That keeps your auth handling, base URL, and error logic in one place.

​
Common mistakes

  • creating one shared key for every integration
  • leaving old keys active after the workflow has been replaced
  • testing a backend flow with a dashboard cookie instead of a real key
  • forgetting to store the raw key when it is first created
  • hardcoding the key into the repo instead of reading it from environment or a secret manager