API clients

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

Code42 Developer Portal
See the Code42 Developer Portal for more API documentation and resources. The portal provides:

Use the Code42 Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Code42 for Incydr users. If you use Code42 APIs that do not appear on the Code42 Developer Portal, contact our Technical Support Engineers for guidance on the best way to integrate with Code42. 

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:

  1. Sign in to the Code42 console.
  2. Select Administration > Integrations > API Clients.

API clients in the console

Item Description
a Create new API client

Creates an 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 Icon > Reset API secret.)

f Actions Icon Select to edit, reset, or delete the API client.
g Details Icon Select to view the details of the API client.

Actions

To perform actions on an API client:

  1. Click Actions Icon to the right of the API client.
  2. 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 Icon

API client details

Item Description
a Actions Icon 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 Icon > Reset API secret.)

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.

API permissions

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.

  1. Sign in to the Code42 console.
  2. Select Administration > Integrations > API Clients.
  3. Click Create new API client.
    The Create new API client dialog appears. 
    Create new API client
  4. Enter a name and description.
    Make the name specific to the API integration or script that uses the API client.
  5. In API permissions, select the APIs for which the API client has read and write permissions.
  6. Click Save.
    The client ID, secret, and base URL appear.
    Create new API client
  7. Click the copy button Icon 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).
  8. Click Done.
    The new API client is displayed in the Code42 console.

Next step: Obtain a token

After you create an API client and have saved the client ID, secret, and base URL, submit the information to obtain an authentication token. The token can only be used for APIs in the Code42 Developer Portal.

  1. Request the token with the /v1/oauth resource.  
    In the following example (using curl), replace <ClientID> with the API client ID, replace <Secret> with the API client secret, and replace <request_url> with the request URL of your Code42 cloud instance (also known as the base URL):
curl -X POST -u '<ClientID>:<Secret>' -d "" <request_url>/v1/oauth

 For example:

curl -X POST -u 'key-79muGw9i424:DWL-mPQ' -d "" https://api.us.code42.com/v1/oauth

A successful request returns an authentication token. For example:

{"access_token":"eyJjdHkiO_bxYJOOn28y...5HGtGHgJzHVCE8zfy1qRBf_rhchA","token_type":"bearer","expires_in":900}
  1. Use the authentication token (also known as a bearer token) in all your API requests. For example, following is an API request to get a list of users:
curl -X GET 'https://api.us.code42.com/v1/users?active=true&blocked=false&pageSize=100' \
-H "authorization: Bearer eyJjdHkiO_bxYJOOn28y...5HGtGHgJzHVCE8zfy1qRBf_rhchA" 

For more information, see Authentication in the Code42 Developer Portal.

Edit an API client

  1. Sign in to the Code42 console.
  2. Select Administration > Integrations > API Clients.
  3. Click Actions Icon on the API client to edit.
  4. Select Edit API client.
    The Edit API client dialog appears. 
    Edit API client
  5. Change the client name, description, and API permissions as desired.
  6. 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.

  1. Sign in to the Code42 console.
  2. Select Administration > Integrations > API Clients.
  3. Click Actions Icon on the API client whose secret you want to reset.
  4. Select Reset API secret.
    The Reset API secret dialog appears.
    Reset API secret
  5. 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.
    API secret reset
  6. Click the copy button Icon 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.
  7. 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.

  1. Sign in to the Code42 console.
  2. Select Administration > Integrations > API Clients.
  3. Click Actions Icon on the API client to delete.
  4. Select Delete API client.
    The Delete API client dialog appears.
    Delete API client
  5. Click Delete.
    The API client is deleted.