API security

API security principles

The Recharge API is used by merchants, partners and ourselves for business critical operations. Security is therefore paramount to the success of both Recharge and its users. For this reason, we invest heavily and follow global standards for the Recharge API security. Our efforts in following API Security principles are strengthened by our users' adherence to general principles of secure use of the interface.

When using API keys in your applications, ensure they are kept secure in transit and at rest. Publicly exposing your credentials can result in unauthorised access and unexpected changes to data. To help keep your API keys secure, we strongly recommend following these best practices.

Authentication, authorization and rights management

Authentication with tokens

Authentication to the API is performed via token-based auth. The token used by a caller of the API is used to identify their application. Callers do not need to provide a username or password.

API requests without an authentication token, or with an invalid token will fail.

OAuth

Recharge supports and encourages the use of OAuth authorization for partner apps.

Scoping

Recharge allows for restricted API tokens by default. We encourage Recharge API users to make use of this functionality and apply PoLP (see Best practices ).

Usage

TLS protocol

All calls must be made via HTTPS. Calls made over plain HTTP will fail.

Rate limits

We purposely limit the number of API requests that any given token can make through the use of a leaky bucket algorithm. For more information on rate limits, refer to API Rate Limits .

Monitoring

• Internal monitoring - Recharge constantly monitors for token leakage, query patterns and activity spikes.
• Vulnerability reporting - Recharge runs a vulnerability reporting program which rewards eligible parties who discover and discretely report verified vulnerabilities in our API and other parts of our platform.

Access and management best practices

Token administration:

• Review and accept the API Terms.
• Manage your users permissions so that only relevant users have access to the API tokens admin section.
• Regenerate your API keys periodically. Then, update your applications to use the newly-generated keys.
• Delete unneeded and unused API keys to minimize exposure to attacks.

Make sure the contact details on API tokens are relevant at all times. Recharge will reach out to this contact for updates and critical information.

For Partners, it is recommended that all Partner applications of Recharge use OAuth to onboard a merchant.

Implementation best practices

Store and manage your tokens safely and securely

• Don't hard code the token in versioning, use .env files.
• Don't use the token in your front-end.
• Make sure you trust the libraries you use for authentication and management.

Review your code

• Review your code before public release to ensure your code does not contain API keys or any other private information. Ensuring your code is peer reviewed will strengthen code quality and shared responsibility.
• Do not embed API keys directly in code. API keys that are embedded in code can be accidentally exposed to the public. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.
• Do not store API keys in files inside your application's source tree. If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.
• Do not store your API keys on the client-side. If you are developing a web app, always store your API keys in a backend server that orchestrates the calls to the Recharge API. If you are developing a mobile app, it’s equally important to NOT store your API keys in the mobile app. Tools exist today that allow a malicious actor to reverse engineer your app and retrieve API keys. Additionally, if you ever need to rotate your API keys, you will need to rely on your users to update your app without which your app will stop working. Instead, we recommend storing third-party API keys such as the ones issued by Recharge in a backend server you own.

Sharing

• Only share when relevant and do not share in communications (email, instant messenger, print, screen share, picture, screenshots).
• If the user has the relevant entitlements they should access the token from the Recharge Merchant Portal.
  • If they do not have the relevant entitlements use a Vault or Password Manager.

Use scoping and restriction:

Set up application and API key restrictions using permission and scope. By adding restrictions, you can reduce the impact of a compromised API key.

• Principle of Least Privilege (PoLP) - Enable API tokens with the least amount of privileges to start with and then iteratively increase the entitlements as needed. Usually you can start by enabling read_only scopes of essential objects and then upgrade the scopes to write when needed.
• Usually you can start by enabling read_only scopes of essential objects and then upgrade the scopes to write when needed.

Token allocation

One token - One application. don’t reuse your token across multiple applications.

Security

In the case your API credentials have been compromised, you should immediately revoke your compromised API tokens and generate new ones.

This prevents a malicious attacker from accessing or modifying your users' data while you transition to new credentials.
You must also inform Recharge about this security incident. You can do so via the Recharge support team.

For more information on Security at Recharge see Security FAQ.