Overview
API clients authenticate access to APIs in the Code42 Developer Portal. An API client contains a client ID and a secret that you submit for authentication much like a username and password. Create an API client for each API integration or script that requires access to the Code42 API.
If you create your own integration or scripts using Code42 APIs, submit the client ID, secret, and base URL with the Auth API to obtain an authentication token to use in your requests (see Authentication in the Code42 Developer Portal).
Considerations
- To create API clients, you must be assigned the Customer Cloud Admin role.
- When you create an API client, the client ID, secret, and base URL appear only once. Save these in a safe place so that when needed you can submit them for authentication of an API integration or script. If you lose the secret, you must reset the secret.
- When you reset an API client secret, the integration or script using that API client loses its authentication. To restore authentication, you must resubmit the new secret.
- Authentication tokens obtained from an API client expire after 15 minutes.
- Basic authentication is deprecated for APIs in the Code42 Developer Portal. For more information, see Code42 API authentication methods.
About API clients
FAQs
API clients in the Code42 console
To view API clients:
- Sign in to the Code42 console.
- Select Administration > Integrations > API Clients.
Item | Description | |
---|---|---|
a | Create new API client | |
b | Client name |
The name of the API client. As a best practice, name the API client to reflect the integration or script for which it is used. |
c | Date created | The date and time the API client was originally created. |
d | Last redeemed | The last time the API client's ID and secret were submitted to obtain an authentication token. |
e | Client ID |
The globally unique ID of the client. Submit this ID with the API client's secret for authentication. (The secret appears only when the API client is created or when you select Actions |
f |
Actions |
Select to edit, reset, or delete the API client. |
g |
Details |
Select to view the details of the API client. |
Actions
To perform actions on an API client:
- Click Actions
to the right of the API client.
- Select an action.
Command | Description |
---|---|
Edit API client | Edits the API client name, description, and API permissions. |
Reset API secret |
Resets the API client secret. After resetting, the new secret appears. Copy the new secret and the client ID to a safe place. When you reset a secret, the API integration or script using that secret loses its authentication. To restore authentication, you must resubmit the new secret with the client ID. |
Delete API client |
Removes the API client. Before you delete an API client, ensure that no API integrations or scripts use that client. Deleting an API client breaks the API integration or script that uses that client. |
API client details
To see API client details, click the details icon .
Item | Description | |
---|---|---|
a |
Actions |
Select to edit, reset, or delete the API client. |
b | Date created | The date and time the API client was originally created. |
c | Last redeemed | The last time the API client's ID and secret were submitted to obtain authentication. |
d | Client ID |
The globally unique ID of the client. Submit this ID with the API client's secret for authentication. (The secret appears only when the API client is created or when you select Actions |
e | API permissions | The API endpoints for which the API client has read and write permissions. |
API permissions
In API client details, API permissions lists the API endpoints that the API client provides permissions to. When you create or edit an API client, select the minimal level of read and write access to ensure least privilege access for your integration or script.
For information about the API endpoints that you can grant read and write access to, see the Code42 Developer Portal.
API permissions considerations:
- Some API endpoints, such as Audit Log and File Events, do not offer write permissions because those APIs function solely for reading system information, not creating it.
- Some APIs listed in API Permissions are named differently in the Code42 Developer Portal. For example, Alert Rules is Rules in the portal, and Data Preferences is Trusted Activities in the portal.
- You cannot use API clients to get read and write permissions for some APIs in the portal, such as Oauth and Customer.
Manage API clients
Create an API client
Before you create API clients, take an inventory of all your API integrations and scripts. Create one API client for each rather than a single API client for many. This way, if one of your API integrations or scripts is compromised, you need only interrupt that one to either reset a secret or create a new API client so you can resume operation. The more granular your API clients, the more flexible you can be when dealing with issues that require you to create new authentication.
- Sign in to the Code42 console.
- Select Administration > Integrations > API Clients.
- Click Create new API client.
The Create new API client dialog appears. - Enter a name and description.
Make the name specific to the API integration or script that uses the API client. - In API permissions, select the APIs for which the API client has read and write permissions.
- Click Save.
The client ID, secret, and base URL appear. - Click the copy button
to copy the client ID, secret, and URL to a safe location.
IMPORTANT: This is the only time the secret is displayed. If you lose the secret for this client ID, you must reset the secret. The base URL corresponds to the API domain of your Code42 cloud instance (see Request URLs in the Code42 Developer Portal). - Click Done.
The new API client is displayed in the Code42 console.
Next step: Obtain a token
Edit an API client
- Sign in to the Code42 console.
- Select Administration > Integrations > API Clients.
- Click Actions
on the API client to edit.
- Select Edit API client.
The Edit API client dialog appears. - Change the client name, description, and API permissions as desired.
- Click Save.
Reset a secret
If you uncover a problem with API authentication, such as a security breach, you can reset the API client's secret. Resetting a secret immediately stops authentication of any API integration or script using the previous secret. Submit the new secret with the client ID to resume authentication.
- Sign in to the Code42 console.
- Select Administration > Integrations > API Clients.
- Click Actions
on the API client whose secret you want to reset.
- Select Reset API secret.
The Reset API secret dialog appears. - Click Reset secret.
The client ID and its new secret are displayed. Note that the client ID is unchanged. It is presented in the dialog with the new secret so you can keep them together. - Click the copy button
to copy the client ID and secret to a safe location.
IMPORTANT: This is the only time the new secret is displayed. If you lose the secret for this client ID, you must reset the secret again. - Click Done.
To use the new secret in the API integration or script, submit it with the client ID to obtain authentication. If you create your own integration or script using Code42 APIs, submit the client ID and with the Auth API to obtain an authentication token to use in your requests (see Authentication in the Code42 Developer Portal).
Delete an API client
Delete an API client when it is no longer needed. However, before deleting an API client, ensure that no API integrations or scripts use it. Deleting an API client that is still in use results in authentication stopping for the API integration or script using it, and you must create a new API client to replace the deleted one.
- Sign in to the Code42 console.
- Select Administration > Integrations > API Clients.
- Click Actions
on the API client to delete.
- Select Delete API client.
The Delete API client dialog appears. - Click Delete.
The API client is deleted.
Related topics
- Authentication in the Code42 Developer Portal
- Code42 integrations resources
- Code42 blog: