Best Practice to Use API Keys for Multi Business Entity

API keys are alphanumeric characters used to access authorized data in Chargebee. You can create multiple API keys to access and control your data.

Chargebee has the following types of API Keys:

• Full-access key
• Publishable key
• Read-only key

Learn more about Chargebee's API key in this article.

API Keys for Multi Business Entity (MBE) Enabled Site

Chargebee allows API key creations only at the site level in MBE-enabled sites, which implies only the Site admin or the site owner can create the API keys.

However, other user categories, such as Business Entity (BE) admins and Finance executives, might also need access to the information belonging to the entities with which they are associated. These users cannot access the API creations page or independently generate API keys because of the difficulties. Instead, the process requires the site admin to create and share keys with the appropriate users following the established method.

Finance Executive

A finance executive has read-only access to the application. However, they have access to the import-export page where they can export data; therefore, they may need an API key to do these operations. In this case, the suggested approach for the site admin is to create a Read-only key exclusive for these users or Finance executive type of user. Learn more to create Read-only keys.

Read Only keys can have either Read All or Restricted access based on Transactional data, Product Catalog data, or both. Choose the option based on the requirement.

Business Entity Admin

A Business Entity (BE) admin has read and write access for all entities to which they have access. They can Create or Modify resources and even import or export data within the entities. To know role-based access of BE admin, click here.

In this scenario, when a business entity admin intends to perform these actions through the API, they must acquire the API key.

Data Exploitation using Full-access Key

When a site admin shares a Full-access key with a business entity admin or any team member of the site, there are below potentials risk associated with it, Such as,

• Data modification: Providing the Full-access API key to any team member makes them the same as an admin because Chargebee uses an API key as a medium to authenticate and control the data access; the site admin should carefully create the API keys for the one who consumes it.
• Data leakage: Using the Full-access key, unauthorized individuals may gain access to the site and data from different entities to which they do not belong.
• Data anomaly: A Full-access key allows users to write, create data across entities and configure site settings, which can lead to data inconsistency.
• Configuration exploitation: A user having a Full-access key has the authorization to add new configurations and modify the existing site's configurations.

Handle Data Exploitations using Full-access Key

A site admin should follow the below recommendations for handling data exploitation using a Full-access key.

• Best API handling practices: To know about how to handle API keys click here.

• Caution usage: To ensure proper handling of Full-access API keys, BE (Business Entity) admins must be encouraged to limit their usage to the entities exclusively assigned to them. You can achieve this by consistently including the business entity ID in the chargebee-business-entity-id header of the API request. For further information on API key usage, please refer to this resource: click here.

      curl https://\{site}.chargebee.com/api/v2/customers  
          -u {site_api_key}: 
          -d first_name="John"  
          -d last_name="Doe"  
          -d email="john@test.com"  
          -H "chargebee-business-entity-id=XyZ1234567Y3np"
  

By including the business entity ID (chargebee-business-entity-id)in the request header, all operations performed by BE administrators will be confined to the specific entity, thereby avoiding any impact on other site data. Site admins are responsible for maintaining the confidentiality of the business entity ID to prevent unauthorized access by non-legitimate BE admins to other business entities' data.

• Distinct keys and operation audits: Following a specific naming convention when creating keys for each BE admin is essential to ensure clear identification of key owners and enable easy filtering for potential issues. This convention should incorporate the following elements:

  • Use a prefix that denotes the key type, such as fk, for the Full-access key.

  • Incorporate the name of the BE admin as the key owner to identify the person responsible for the operations allowed by the key; here james is the name of the person to whom the key belongs, with write operation. For example, if a BE admin named James needs a key for importing data, you should name the key as:

                fk-james-write-key
    

By adhering to this naming convention, the key name itself will provide valuable information about its purpose and ownership. In data exploitation, investigating and narrowing down the issue will be much easier by accessing the event page and applying filters, such as filtering by event source = API and operations name.

Following this naming convention for keys enhances the system's clarity, accountability, and security.

Monitor and track API key usage to maintain accountability and detect unusual or unauthorized activities.

Key Sharing

Chargebee does not encourage people to share keys via an unencrypted channel, you should keep the keys in the merchant vault, and an authorized person should access the vault to get the keys. Please refer to the Sharing Keys concept in this document.

If the vault is not implemented, the API keys are securely transmitted via a secure process.