Overview

An API Key is an authentication code that is used by the issuer (CommBox) to recognize other platforms with which it communicates. To secure this powerful access tool from being used by anyone other than you (the specific CommBox client), CommBox encrypted the API Key into a Secret.

Key Considerations

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

B. 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.

C. 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.

D. 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.

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

Copying the API Key

1. Navigate to Settings > API Key.

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. When the dialog box opens, 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 records 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 days 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.
   

Questions and Answers 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.