Overview

An API Key is an authentication code that is used by the issuer (CommBox) to recognize your organization’s platform when it communicates with the issuer’s platform. 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.

Following common security standards, CommBox now 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.

Note: Admin access is required to change the API key.

Some organizations do not have API interactions. If your organization is not using API keys to connect CommBox with other systems, this topic is irrelevant to you. Ignore system messages about the API Key. No action is required.

To copy and manage your personal CommBox API Key:

1. Navigate to Settings > Modules > API Key.
2. You may verify that the key is valid by clicking the Testing icon. Expect a green confirmation box at the bottom right 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.

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

In the event of a concern about privacy or security risk, 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 > Modules > API Key.
2. Click the Revoke icon at the far right of the existing API Key.
   A new dialog box will inform you have 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 days grace period.
4. Finish the process by clicking Done.
   The New API displays 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.

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.