Docs
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:
Learn more about Chargebee's API key in this article.
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.
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.
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.
Currently, Chargebee does not permit Business Entity admins to generate their API keys; nonetheless, this capability is planned for the future, enabling BE admins to create keys restricted to specific entities. Presently, Site admins are responsible for generating Full-access keys. Learn more to create 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,
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.
Articles & FAQ 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.
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.
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.
Sharing API keys are security-sensitive matter. We strongly recommend following these guidelines when sharing API keys: