API authentication methods

Overview

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

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

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

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

Considerations

• Basic authentication is deprecated for use with APIs in the Developer Portal. Basic authentication will continue to be supported for APIs not in the Developer Portal. For more information about this and other API deprecations, see 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 API.

Comparison of API authentication methods

The Incydr API offers the following authentication methods:

• Obtain a token with an API client (only applies to APIs in the 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 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 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 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 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 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 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 Incydr 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}

2. 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 Developer Portal.

Use basic authentication

Basic authentication is deprecated for use with APIs in the Developer Portal. Basic authentication will continue to be supported for APIs not in the Developer Portal. For more information about this and other API deprecations, see API release notes.

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

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

Replace <request_url> with the URL of your Incydr 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

Basic authentication is deprecated for use with APIs in the Developer Portal. Basic authentication will continue to be supported for APIs not in the Developer Portal. For more information about this and other API deprecations, see API release notes.

Step 1: Get the token

1. Include your username in a GET request to auth/jwt and supply your password when prompted.

   curl -u "username" '<request_url>/api/v3/auth/jwt?useBody=true'

   Replace <request_url> with the address of your incydr environment (do not include the brackets in your request). The request URL you use in your authentication request depends on your Incydr 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 Incydr 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.

   curl -u "username" -H "totp-auth: 424242" '<request_url>/api/v3/auth/jwt?useBody=true'

    
2. 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 Incydr environment (do not include the brackets in your request). 

External resources

• Project page for curl
• Man page for curl
• Documentation for curl

Related topics

• Authentication in the Incydr Developer Portal
• API clients
• incydr API resources
• Incydr API syntax and usage 
• Sample uses of the Incydr API 
• Tools for interacting with the Incydr2 API