API ReferenceTheme Engine ReferenceJavaScript SDK ReferenceRecharge Help CenterContact Us

API security

Suggest Edits

API security principles

Our API is used by our merchants, our 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 our API security. Our efforts in following API Security principles are strengthened by our users' adherence to general principles of secure use of the interface.

Below is a non-exhaustive, but representative, list of standards we follow, and best practices we recommend to users of the Recharge API.

🚧

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

We support and encourage the use of OAuth authorization for partner apps.

  • Scoping

We allow for restricted API tokens by default. We encourage our 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, please refer to the API Rate Limits page.

  • Monitoring
  • Internal monitoring - We constantly monitor 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.

Recommended best practices

Access and management

  • 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, we recommend that all Partner applications of Recharge use OAuth to onboard a merchant.

Implementation

  • 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.
  • 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.

🚧

Note

  • 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.
    • Where possible:
      • 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.
      • Do not share in communications (email, instant messenger, print, screenshare, picture, screenshots).
    • Use scoping and restriction:
      • 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.

❗️

Scoping restriction to improve security

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

  • Token allocation
    • One token - One application => don’t reuse your token across multiple applications.
  • Make sure you trust the libraries you use for authentication and management.

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.

📘

Security at Recharge

For more information on Security at Recharge and our certifications (see Security FAQ).

Updated 5 months ago

Suggested Article

Need Help? Contact Us