What an API key is
An API key is a credential built for machines rather than people. When one backend calls another over HTTP, there is no human to type a password and no browser session to lean on, so the caller proves its identity by presenting a secret value that was issued to it in advance. The API looks up that value, recognises the account it belongs to, and then processes the request under that account's identity. The key is typically a long, high-entropy string — long enough that it cannot be guessed and unique enough that it maps to exactly one account.
Because the key is a bearer credential, anyone who holds it can act as the account it belongs to. That makes two properties essential. First, secrecy: a key is sent only over an encrypted (HTTPS) connection and is stored on the server side of an integration, never embedded in a web page, mobile app, or anything a customer's browser can read. Second, revocability: if a key is exposed, it must be possible to disable it and issue a replacement without changing the account itself. Issuing, rotating, and revoking keys is how an integration limits the blast radius of a leak.
Authentication is only half of what a well-designed key does. The other half is authorization — deciding not just who is calling but what they may do. A scoped key carries a limited set of permissions, so a key minted for one purpose cannot be turned around and used for another. A key that can read data cannot necessarily move funds; a key issued for a test environment cannot reach production. Scoping turns one all-powerful secret into several narrow ones, each of which is safe to deploy where it is needed and harmless where it is not.
Why it matters for crypto payments
A payments API sits in front of money, so the credential that opens it is a sensitive asset in its own right. A leaked key is not merely a data-exposure problem: depending on what it is allowed to do, it could read transaction history, create charges, or initiate transfers. That is why scoping is not a nicety on a payments platform but a core control — the narrowest key that still does the job is the safest one to hand to any given service, and a read-only key embedded somewhere it should not be does far less damage than an all-access one.
Server-side placement matters for the same reason. Because a crypto payout settles on-chain and cannot be reversed, a credential that can move funds must never sit anywhere a customer or third party can reach it. The key lives on the merchant's backend, behind their own access controls; the customer-facing checkout page and any browser code talk to that backend, not directly to the payments API with a money-moving key. Keeping the secret on the server, scoping it to the smallest useful set of operations, and rotating it on a schedule together form the baseline hygiene for any integration that touches value.
API keys on halfin
halfin authenticates API requests with a key supplied in the X-API-Key header. Every call your backend makes to the halfin API carries this header; the platform matches the key to your merchant account, then checks that the key is permitted to perform the specific operation being requested before doing any work. A key that lacks the permission for an endpoint is refused, so the same account can hold several keys with different reach — for example one that only reads invoices and balances, and a separate, more tightly held one that is allowed to create payouts.
Keys are managed from the merchant dashboard, where they can be created, scoped, and revoked. The practical pattern is to issue a distinct key per integration or service and grant each one only the operations it actually needs, so that revoking a single key contains an incident without disrupting the rest of your setup. The X-API-Key header is also how halfin separates roles: it authenticates the merchant's own server-to-server calls — creating invoices, listing balances, submitting payouts — which is a different mechanism from the token-based access used by the customer-facing hosted checkout and from the HMAC signature that authenticates the webhooks halfin sends back to you.
- An API key is a secret credential that authenticates a server-to-server request and maps it to one account.
- On halfin it is sent in the X-API-Key header and checked against the permissions the key was granted before any operation runs.
- Keys are scoped: a read-only key cannot move funds, so the narrowest key that does the job is the safest to deploy.
- Keep keys server-side, never in browser or client code, and rotate or revoke them from the dashboard if one is exposed.