Authentication
Authenticate every merchant API request with a secret API key.
Send your secret key in X-API-Key for every request. This includes currencies and rates.
curl 'https://api.thehalfin.com/v1/invoices?limit=20' \
--header "X-API-Key: $HALFIN_API_KEY"API key authentication#
A key belongs to one merchant and one environment. sk_live_ accesses live data; sk_test_ accesses test data. The server derives both from the authenticated key. Do not send merchant_id, X-Merchant-ID, or an environment query parameter to select a different scope.
Merchant API requests do not use Authorization: Bearer. Keys and webhook endpoints are managed through the dashboard, under the user's account permissions.
Permissions#
Each operation lists its required permission. write does not include read: creating and subsequently reading an invoice requires both invoices:write and invoices:read.
Every valid API key can read the currency and rate catalogs through the implicit catalog:read permission. You do not add that permission when creating a key.
Authentication errors#
| Response | Meaning |
|---|---|
401 unauthorized | The key cannot authenticate this request. Check the key, environment, revocation, and merchant access. |
403 forbidden | The authenticated key lacks the operation's permission. |
403 api_key_ip_forbidden | The request was rejected by the key's IP restriction. See IP access. |
A 401 does not disclose whether the key is unknown, expired, revoked, or otherwise unusable. Repeating it without correcting the credentials will not help.
Keep keys server-side#
Store keys in a secret manager. Never embed them in a browser, mobile application, public repository, URL, analytics event, or application log. Use separate keys for incoming payments, outgoing payments, and reconciliation. See API keys for permissions and replacement.