API Key

An API key is a long, randomly generated string of characters that a software program presents when it calls an application programming interface. The service receiving the call uses the key to work out which customer is making the request and whether to accept it. In payments, the key is what allows a merchant's server to tell its payment provider to charge a card, issue a refund or send a payout without a person logging in.

An API key is a credential in the same sense as a password, and anyone who holds it can act as the account it belongs to. It identifies an application or account, not an individual user, which distinguishes it from delegated schemes such as OAuth, where a user grants a third party limited access. Most payment gateways, payout platforms, banking-as-a-service providers and data aggregators issue keys for their REST APIs.

When a business opens an account with a payment provider, the provider's dashboard generates one or more keys. The business stores the key on its server and includes it in each request, usually in an HTTP header, over a connection encrypted with Transport Layer Security. The provider looks up the key, identifies the account, checks the key's permissions and processes the request.

As an example, an online shop's server might send a request to create a payment of 50 dollars, with its key in the authorization header and an idempotency key to prevent a double charge if the request is repeated. The provider replies with a payment object and later confirms the outcome through a webhook notification.

Payment providers usually issue several kinds of key for different purposes.

• Publishable keys. These are designed to appear in a web page or mobile app. They can only do harmless things, such as turning card details into a token, and cannot move money.
• Secret keys. A secret key can create charges, refunds and payouts and read account data. It must stay on the server and never be sent to a browser or included in an app.
• Restricted keys. These carry a subset of permissions, for example read-only access to reports, so that a single system or contractor receives only what it needs.
• Test and live keys. Keys for the sandbox environment work only with simulated money, while keys for the production environment move real funds. Providers often mark the two with different prefixes so that they are hard to confuse.

A leaked secret key lets an attacker act as the merchant. Typical abuse includes sending payouts or refunds to accounts the attacker controls, using the merchant's account for card testing, and downloading customer data. Keys leak most often through human error: being committed to a public code repository, pasted into support tickets or chat tools, embedded in a mobile app, or left in log files. Automated scanners search public repositories for strings that look like keys, and some providers scan as well and revoke keys they find.

Because a key by itself is a single factor, a request carrying a valid key is trusted unless other controls are in place. This makes high-value operations, such as payouts, a particular concern.

Good practice treats keys as secrets with a managed life cycle.

• Storage. Keys are kept in a secrets manager or environment configuration, not in source code, and access is limited through role-based access control.
• Least privilege. Each system receives a restricted key with only the permissions it needs.
• Rotation. Keys are replaced on a schedule and immediately after staff changes or suspected exposure, a practice called key rotation. Providers support this by letting old and new keys overlap briefly.
• Network limits. Many providers let a customer restrict a key to a list of approved IP addresses, so that a stolen key is useless from elsewhere.
• Monitoring. Unusual volumes, new destinations and calls from unfamiliar locations are flagged, and rate limiting caps how fast any key can be used.

For sensitive operations, providers add or substitute stronger mechanisms. Requests may have to be signed with a private key, so that the provider can verify both the sender and that the content was not altered, using a digital signature. Bank and open banking interfaces commonly require mutual authentication with client certificates, and short-lived access tokens in place of long-lived keys. Webhooks travelling in the other direction are verified with a separate signing secret.

Security standards do not ban API keys but expect them to be controlled. The PCI DSS requires that credentials used by applications and systems are protected, changed periodically and not hard-coded, and audits such as a SOC 2 report examine how a company issues, stores and revokes them.