API Keys

What Is an API?

API stands for application programming interface. You can think of an API as a way for one application to communicate to another. In order for you, or other applications to interface with Recurly, you'll need to use an API key. You can think of an API key as a password, which Recurly uses to help identify the program making the request.

Find or Generate Your API Key

If you want to set up an integration with your Recurly account, chances are high that you'll need to generate an API key. Users with Manager permissions can generate and view their own API keys. Users with Admin permissions can also see API keys for other account users. Below, you'll learn how to grab an existing API key or generate a new one.

1. As a developer or Admin user, navigate to Integrations > API Keys.

2. Navigate to the bottom of the screen and click the Add Private API Key button

3. Add a name for your API key, any notes about what it will be used for, and a third-party application for which the application applies.

4. Click Save Changes.

Revoking an API key

If you would like to revoke an API key, you can do so by following the steps below. We recommend that you revoke your API key if you have any reason to believe the security of the key may be compromised.

1. As a developer or Admin user, navigate to Developers > API Keys.

2. Find the key you would like to revoke.

3. You have three options: revoke the key permanently, to regenerate the key immediately, or to regenerate the key within 12 hours.

Immediately Revoke

If you revoke the key, we will not create another key, and it will immediately stop working. All applications that have access to Recurly via that key will immediately cease to have access.

Regenerate Immediately

If you regenerate a key immediately, the old key will stop working, and Recurly will issue you a new API key. All applications that have access to Recurly via the old key will immediately cease to have access, and we recommend that you update applications with the new key.

Base64 Encoded API Keys

If you need a Base64 encoded API key, you can copy from Recurly without having to convert yourself. Go to Integrations > API Credentials in Recurly and click to expand "Need help using the API Key?". Your Base64 encoded API key is the characters after "Authorization: Basic"

Regenerate after 12 hours

If you choose this option, the old key is still valid for 12 hours, and Recurly will generate a new key. This will allow you time to update applications using the old key to the new key. During the 12-hour period, applications using the old key will not be affected and will be able to authenticate as if nothing has changed. When 12 hours passes, the old key will no longer function.

API Key Security

API keys grant full access to your Recurly account and should be protected the same way you would protect your password. In particular, there are a few common scenarios to keep in mind when working with API keys.

• Give each integration its own API key, and assign labels to each key so you know which key goes with which application. If a specific API key is compromised, you can disable that key without disabling access to all of your other integrations.
• Be careful not to expose the key to the public (such as in screenshots, videos, or help documentation). Remember that blurring your data isn't always enough. It's best to use "cut" functions in your graphics program to remove the data completely.
• If a key needs to be shared, generate a new key and label it accordingly so it can be disabled, if needed. Never email the API key, because it would allow access to your Recurly account if hackers were to compromise your email account.
• If you revoke a user's access to your Recurly account, any API keys created by the user will be removed from your account.
• Do not embed, store, or expose your API key(s) within client-side code, including JavaScript, mobile applications, and native executables. A bad actor can decompile your application and obtain your API key(s).

Additional Support

If you require further support, please contact Recurly Support and we will be happy to assist you.