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:

sign in to the merchant dashboard
open Advanced
create a key in the key manager
copy the raw key immediately
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

Recommended key lifecycle

Step	Good practice
Create	Name the key for the system that will use it
Store	Put it in a secret manager immediately
Use	Restrict it to backend or bot-side code
Review	Check when it was last used and whether it is still needed
Revoke	Remove 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:

Permission	Use
`access:read`	Check entitlements and read Pay API rails
`access:write`	Create Pay API apps, products, and payment sessions
`access:webhooks`	Register 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:

create the replacement key in the dashboard
store it in your secret manager
deploy the new value to the system that uses it
make one read call such as GET /v1/products to confirm it works
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.

Start here

After payment

Examples and reference

API keys

API keys

Create a key from the dashboard

How to send the key

What API keys should call

Use API keys only on your backend

Recommended key lifecycle

A production-friendly key setup

Rotation playbook

Naming pattern that works well

First request examples

cURL

TypeScript

Python

A small server wrapper that scales well

TypeScript

Python

Common mistakes

Common questions

What permissions should a Hilt API key have?

Can I recover a raw API key later?

Should API keys be used in browser code?

Can an agent create its own Hilt Pay API key?

​API keys

​Create a key from the dashboard

​How to send the key

​What API keys should call

​Use API keys only on your backend

​Recommended key lifecycle

​A production-friendly key setup

​Rotation playbook

​Naming pattern that works well

​First request examples

​cURL

​TypeScript

​Python

​A small server wrapper that scales well

​TypeScript

​Python

​Common mistakes

​Common questions

​What permissions should a Hilt API key have?

​Can I recover a raw API key later?

​Should API keys be used in browser code?

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

API keys

Create a key from the dashboard

How to send the key

What API keys should call

Use API keys only on your backend

Recommended key lifecycle

A production-friendly key setup

Rotation playbook

Naming pattern that works well

First request examples

cURL

TypeScript

Python

A small server wrapper that scales well

TypeScript

Python

Common mistakes

Common questions

What permissions should a Hilt API key have?

Can I recover a raw API key later?

Should API keys be used in browser code?

Can an agent create its own Hilt Pay API key?