Code42 API authentication methods

Overview

Most requests to the Code42 API must be authenticated. This article describes the available Code42 API authentication methods and provides examples of their use.

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

A single access point for documentation of methods for Incydr, including Code42's REST API, Python SDK py42, and command-line interface (CLI)
A single request URL for Code42 API calls to each cloud instance
API reference documentation

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

Basic authentication is deprecated for use with APIs in the Code42 Developer Portal. Basic authentication will continue to be supported for APIs not in the Code42 Developer Portal. For more information about this and other API deprecations, see Code42 API release notes.
The examples in this article use curl, but the concepts apply to other tools that can be used to interact with the Code42 API.

Comparison of Code42 API authentication methods

The Code42 API offers the following authentication methods:

Obtain a token with an API client (only applies to APIs in the Code42 Developer Portal): You obtain a temporary authentication token that is good for 15 minutes and use it to authenticate API requests.
Use basic authentication (deprecated for APIs in the Code42 Developer Portal): You provide your username and password to authenticate each API request.
Use basic authentication to obtain a token (deprecated for APIs in the Code42 Developer Portal): You obtain a temporary authentication token that is good for 30 minutes and use it to authenticate API requests.

The following table describes the advantages and disadvantages of each authentication method:

Authentication method	Advantages	Disadvantages
Obtain a token with an API client	Better performance than basic authentication More secure than a token obtained with a username and password Utilizes a secret that can be reset if needed Tokens expire in 15 minutes	Can only be used with APIs in the Code42 Developer Portal More complex to use than basic authentication
Use basic authentication	Simple to use	Passwords may be saved in the history of your tool Not allowed for version 3 resources, except for the resource that provides a token Deprecated for use in the Code42 Developer Portal
Use basic authentication to obtain a token	Better performance than basic authentication More secure than basic authentication (tokens expire in 30 minutes)	More complex to use than basic authentication Not as secure as a token obtained with an API client Deprecated for use in the Code42 Developer Portal

Authentication method

Advantages

Disadvantages

Obtain a token with an API client

Better performance than basic authentication
More secure than a token obtained with a username and password
- Utilizes a secret that can be reset if needed
- Tokens expire in 15 minutes

Can only be used with APIs in the Code42 Developer Portal
More complex to use than basic authentication

Use basic authentication

Simple to use

Passwords may be saved in the history of your tool
Not allowed for version 3 resources, except for the resource that provides a token
Deprecated for use in the Code42 Developer Portal

Use basic authentication to obtain a token

Better performance than basic authentication
More secure than basic authentication
(tokens expire in 30 minutes)

More complex to use than basic authentication
Not as secure as a token obtained with an API client
Deprecated for use in the Code42 Developer Portal

Obtain a token with an API client

To obtain a token, first create an API client.

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.

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}

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.

Use basic authentication

To use basic authentication, include your Code42 username in the API request and supply your password when prompted.

curl -u "username" <request_url>/api/v1/Computer

Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request):

You can use basic authentication for any version 1 or 4 and later resource, and version 3's /auth/jwt resource.

Use basic authentication to obtain a token

Step 1: Get the token

Include your Code42 username in a GET request to auth/jwt and supply your password when prompted.
Copied!
```
curl -u "username" '<request_url>/api/v3/auth/jwt?useBody=true'
```
Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request). The request URL you use in your authentication request depends on your Code42 cloud address.

Authentication cookies are not supported
You must include the ?useBody=true query parameter in the auth/jwt request to return the token in the response body. Omitting the ?useBody=true query parameter or using ?useBody=false results in the token being returned in an authentication cookie, which is not supported by the Code42 API. Include the returned token in subsequent API requests using the authorization header with the Bearer scheme, for example, -H 'authorization: Bearer <token>'

If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the six- to eight-digit Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. (Sending the request without the TOTP displays the error message TIME_BASED_ONE_TIME_PASSWORD_REQUIRED.) The example below includes a TOTP value of 424242.
Copied!
```
curl -u "username" -H "totp-auth: 424242" '<request_url>/api/v3/auth/jwt?useBody=true' 
```
From the reply, copy the value of the v3_user_token. In the example below, it is eyJjdHki...txd546Eg
```
{"data":{"v3_user_token":"eyJjdHki...txd546Eg"},"error":null,"warnings":null}
```

Step 2: Use the token in API requests

Include that token in API requests. For example:

tkn="eyJjdHki...txd546Eg"
curl --header 'Authorization: Bearer '$tkn <request_url>/api/v1/User
curl --header 'Authorization: Bearer '$tkn <request_url>/api/v3/org/<organizationID>/user
curl -H 'Authorization: Bearer '$tkn <request_url>/api/v4/role/view

Replace <request_url> with the address of your Code42 environment (do not include the brackets in your request).

Overview

Considerations

Comparison of Code42 API authentication methods

Obtain a token with an API client

Use basic authentication

Use basic authentication to obtain a token

Step 1: Get the token

Step 2: Use the token in API requests

External resources

Related topics