​
API keys

If you are starting from zero tonight, follow Developer quickstart first and use this page as the deeper key-handling reference. Hilt API keys are for server-side merchant integrations and Hilt Pay API automation. They let a merchant’s own backend, bot, or automation call the public Hilt API directly from server-side code. If an AI agent or developer tool is doing the initial setup, use Agent setup first. Agent Bootstrap creates a sandbox setup intent and a temporary sandbox key before the owner approves live credentials.

​
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
  • Hilt Pay API apps, products, rail settings, payment sessions, entitlement checks, and webhooks
  • 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. For Hilt Pay API, create the narrowest key possible:
PermissionUse
access:readCheck entitlements and read Pay API rails
access:writeCreate Pay API apps, products, and payment sessions
access:webhooksRegister webhook endpoints for Pay API flows
Agent Bootstrap keys are different from normal live keys. They are temporary sandbox setup keys. They can prepare and test an integration, but they cannot move live money, change account billing, or bypass owner approval. Default keys do not receive Pay API permissions automatically. If you use the Hilt sandbox v1, a sandbox key now has a clearer purpose too:
  • run simulated testing sessions safely
  • separate pre-launch sandbox testing from live automation
  • keep lower-risk integration work distinct from production traffic

​
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
  • giving an agent a broad live key before it has proven the setup in sandbox

​
Common questions

​
What permissions should a Hilt API key have?

Use the minimum permissions needed. Most server-side integrations need read; checkout creation or webhook subscription workflows may also need execute.

​
Can I recover a raw API key later?

No. Store the raw key immediately when it is created. If it is lost, create a replacement key, deploy it, test it, and revoke the old key.

​
Should API keys be used in browser code?

No. Hilt API keys belong in server-side code, bots, secure automation, or secret managers, not public browser code.

​
Can an agent create its own Hilt Pay API key?

An agent can start a sandbox setup intent and receive temporary sandbox credentials. A live key still requires owner approval because live keys can create production sessions, webhooks, and entitlement state.