The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

API Keys

Recurly uses API keys to authenticate calls to the Recurly API.

Recurly uses HTTP Basic Authentication. Your API key is securely encrypted by the SSL channel. Read more in our Developer Documentation.

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 Developers > API Keys.
  1. Navigate to the bottom of the screen and click the Add Private API Key button
  1. 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.
  1. 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.

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.

Additional Support

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