Authentication

All merchant API requests authenticate with an API key in the X-API-Key header. Dashboard login, MFA, and checkout token flows are first-party UI surfaces and are not part of the public merchant API.

API key types

Keys are 64-character hex strings: sk_test_{64 hex chars} or sk_live_{64 hex chars}.

Header format

X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000

Pass the same key on every server-side request.

curl https://api-sandbox.thehalfin.com/v1/invoices \
  -H "X-API-Key: $HALFIN_API_KEY"

import { createHalfin, listInvoices } from '@halfin/sdk-merchant';

const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY! });
const { data } = await listInvoices({ client });

Environment isolation

Test and live environments are completely separate:

• A test key only sees test invoices, balances, and resources.
• A live key only sees live invoices, real blockchain transactions, and live resources.
• You cannot mix environments — a test key will never see live data.

Best practices

• Rotate keys periodically in Settings → API Keys on the dashboard.
• Use test keys in CI/CD pipelines and staging environments.
• Restrict scopes — create keys with only the permissions your integration needs (e.g. invoices:write without payouts:write).
• Keep live keys server-side only — never expose them in frontend code or client bundles.

Troubleshooting

401 Unauthorized — the key is missing, malformed, revoked, or from the wrong environment.

403 Forbidden — the key is valid but does not have the permission required by the endpoint. Check the key's scope in Settings → API Keys.