API Key

Overview

The API module covers topics related to CommBox APIs, focusing primarily on authentication using an API Key (Bearer Token).

An API Key is an authentication credential used by CommBox to identify and authorize external platforms that communicate with its services.

Because an API Key provides powerful access, it must be protected from unauthorized use. To ensure that only the intended CommBox client can use it, CommBox encrypts the API Key into a Secret, periodically rotates its value at preset intervals, and requires users to provide a one-time password (OTP) as an additional layer of security.

Key Considerations

A. Developers can configure all API payloads to include the UTC time zone indicator (Z suffix) for all DateTime fields, ensuring consistent, time zone–explicit values across integrations and simplifying downstream processing for systems that standardize on UTC.

B. Admin access is required to change the API key.

C. The API Key is required for every API interaction. To authenticate the API process, copy the API key from the CommBox platform and paste it into the Authentication section of the API under Bearer Token.

D. Following common security standards, CommBox regularly rotates the API keys to ensure that the data and information remain secure. Each API Key replaces the old one and is valid for up to a year. Once a key is revoked, automatically by CommBox or manually by an admin, a grace period of up to 30 days allows the admin to replace the key within the organizational systems.

E. Some organizations have limited API interactions and use our platform in ways that make expiration reminders easy to miss. Such organizations can configure the API key to run continuously without expiration, helping them avoid downtime caused by unnoticed security alerts.

F. Some organizations do not have any API interactions. Please ignore system messages about the API Key. No action is required.

UTC Time Zone Indicator

To add UTC zone indicator (Z suffix) for all DateTime fields, navigate to Settings > API and enable ISO 8601 UTC Format in the General section. Once enabled, timestamps are returned in ISO 8601 UTC format (e.g., 2025-11-23T12:44:11) in all API payloads.

Copying the API Key

1. Navigate to Settings > API and expand the API Keys section.

2. You may verify that the key is valid by clicking the testing icon. A green confirmation box will appear at the bottom corner of the screen.

3. Click on the View icon next to the API key.
   

4. The dialog box will request that you enter the code sent to your email address and click Continue. You must be designated as an Admin for this procedure.
   

5. A new dialog box opens with the API key. Click the Copy icon to the right of the key and paste it wherever it is needed in your system.
   

API Key Management

The API Key table displays the status of the current and last API Keys, their expiration date, last time they were used, and when they were created.

A new API key will be generated automatically in the preset schedule you set up or after 365 days by default. You will receive a 30-day advance notice before to the API key expiration date.

In the event of a security breach or a concern regarding privacy or security, you may revoke and issue a new API key sooner than the scheduled rotation.

To manually revoke the current API key:

1. Navigate to Settings > API Key.

2. Click the Revoke icon at the far right of the existing API Key.
   A new dialog box will inform you that you have a 30-day grace period to replace the old key with the new one. Click the Revoke Key button.
   

3. At the new dialog box, determine how long the new key will be active. You may copy it to other locations from there or do so later within your 30-day grace period.
   

4. Finish the process by clicking Done.
   The new API will be displayed above the old one. After 30 days, the old API will expire.

5. You may delete the Revoked / Expired key by clicking the Trash Bin icon.

To set the API key to Never Expire

While we don’t recommend doing so, you may choose to set the API key to Never expire settings.
To make the API key continuously valid:

1. Click on the unlock icon.
2. Confirm that you want to remove the expiration functionality by clicking Remove Expiration.
   

FAQs about the API Key Rotation

Q: Why is the API key changing?

A: The API key is fixed and doesn’t change until we issue a new one.
The API Key is encrypted in a Secret with an expiration date component, after which the API Key will not be accepted by our system. It is this component that makes the Secret change daily.

Q: How can I see the actual API Key?

A: Retrieving the actual API Key that is embedded in the secret will enable you to search for it within your platform.

1. Goto a decoding website such as www.jwt.io
2. Copy the API Key as it appears on the CommBox API setting page.
3. Paste the API Key (encrypted in Secret) into the left window.
   The decoded API Key is the 2nd number in the main payload section labeled “client_secret” (in purple).

Q: How can the old and the new API Keys work at the same time?

A: CommBox has a master list with all active API keys issued to each of our clients. This list allows for the overlapping keys to be accepted. Once the expiration date arrives, we delete the old key from the list of operational API keys.