Authentication

API Version

Product Catalog

Library

Chargebee uses HTTP Basic authentication for API calls. The username is your API key while the password is empty. You can obtain your API keys from the admin console.

Note: The API keys are different for your test site and your live site.

Note

Select the programming language of your choice from the Library dropdown at the top of the page.

This section shows you how to authenticate API calls using the Chargebee Billing client library.

Global configuration

For Node.js, use the Chargebee to configure your site and your API key. It is a global configuration and can be setup as part of your server initialization

const chargebee = new Chargebee({
  site: "{site}",
  apiKey: "{site_api_key}",
});

Making API calls to specific Chargebee sites

If you operate multiple Chargebee sites and need to target a specific site for an API call, simply specify the site name and corresponding API key in the API request. Here's an example of how to do this while calling the Create a customer API using the Chargebee Billing client library:


import Chargebee from "chargebee";

// Creating multiple instances of Chargebee for different sites.
const chargebeeSiteUS = new Chargebee({
  apiKey: "{api-key}",
  site: "{my-site-us}"
});

const chargebeeSiteEU = new Chargebee({
  apiKey: "{api-key}",
  site: "{my-site-eu}"
});

async function createCustomer() {
  try {
    const result = await chargebeeSiteUS.customer.create({
      first_name: "Stuart",
      last_name: "Little"
    });

    console.log(result);
    const customer = result.customer;
  } catch (err) {
    console.log(err);
  }
}

async function createCustomerEU() {
  try {
    const result = await chargebeeSiteEU.customer.create({
      first_name: "Stuart",
      last_name: "Little"
    });

    console.log(result);
    const customer = result.customer;
  } catch (err) {
    console.log(err);
  }
}

createCustomer();
createCustomerEU();

API keys are unique strings used for both authenticating and identifying an application communicating with Chargebee. This section describes the best practices that developers can follow to secure Chargebee API keys.

Storing keys: Do not store API keys in files that get checked into your application code repository. This is especially important if your repository is public. Review your code for any API keys before publishing.
Delete keys that are no longer needed; this prevents misuse. Although GET requests do not generate any events, you can check API key usage for POST requests by fetching all events with source set to api. Among the events returned, filter the API key name found in the event.user attribute.
Limit the scope of keys by using different keys for different apps. This helps in the following ways:
- Any given key acts as an identifier for the service that uses it.
- When a key is compromised, you only have to change it for the affected app.
Use an informative naming scheme for your keys: When choosing a name for the API key, use a consistent format such as <service name>-<key creation timestamp> (for example: core_app-09-12-2020).
Use keys of the appropriate type: Avoid using full access keys when publishable or read-only keys are sufficient.
Rotate API keys periodically: It is recommended that you change your API keys periodically just like passwords. This should be done especially when you notice any anomalies in API usage. Create a new key and replace all occurrences of the old key with the new one. Thereafter, delete the old key. We recommend changing keys at least once in 3 months.

Sharing keys: Suggested below are guidelines around sharing API keys with people:

API keys can be viewed and created by users with admin access to Chargebee.
When sharing keys with non-admins, do so using a medium that is secure, has appropriate access restrictions, and is destroyed after key sharing. Suggested options are: a secure cloud-based document sharing service or a password manager that allows sharing over a network.
Do not share keys via emails or other plaintext communication.
Keep a tab on the number of people who have admin access to Chargebee. Revoke said access for users who no longer need it, so that newer keys aren't available to them unnecessarily.
When sharing keys with a third party for integrations, ask about their API request volumes so that your overall API rate quotas are not breached.

Authentication examples

Global configuration

Making API calls to specific Chargebee sites

API keys: best practices