API clients

Overview

API clients authenticate access to APIs in the Incydr 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 Incydr API.

If you create your own integration or scripts using Incydr 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 Incydr Developer Portal).

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

• 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 Incydr Developer Portal. For more information, see API authentication methods.

About API clients

Least privilege

API clients enforce the principal of least privilege. By setting the API permissions of an API client to just the minimal read and write permissions needed, you can ensure that the integration or script using the API client has access to only the necessary parts of Incydr.

This model provides great advantage over tying access to a user account because you can limit an API client to a more narrow scope of functionality than you would a user. And because API clients are not tied to a user lifecycle, it means your integration or script is not tied to the employment status of any one individual.

Secrets

All requests to Incydr require authentication. For example, when you sign in to the Incydr console, you enter your username and password to get authenticated for access. In a similar way, integrations or scripts that connect to Incydr need authentication. You could enter a username and password to get authentication, but that is not as secure as using an API client ID and secret.

The secret is what makes an API client powerful. If you uncover a problem with API authentication, such as a security breach, you can reset the API client's secret to immediately stop authentication of any integration or script using that API client. Once the breach is resolved, you simply submit the new secret with the client ID to resume authentication.

FAQs

Can we still use other authentication methods to authenticate API access?

Basic authentication is deprecated for APIs in the Incydr Developer Portal. You can still use basic authentication for APIs not in the Developer Portal. For more information, see API authentication methods.

For the best security you should use API clients. API clients create Oauth 2.0-compliant tokens that provide a high level of security for your API requests. 

How do I update my existing API integrations to use tokens from API clients?

If you create your own integration or script using Incydr APIs, inventory the integration to find all the places that use basic authentication (username/password). Then replace those instances with commands to create and use tokens generated from API clients. For the commands, see Authentication in the Incydr Developer Portal.

What happens when a token expires?

Authentication tokens obtained with an API client expire every fifteen minutes. This expiration period ensures that the token authorizes access for the current application session, but doesn't provide access beyond that. If the token expires during the current session, service continues uninterrupted, since authorization was already granted at the beginning of the session. But once the session ends and the token expires, the application is forced to make the API integration or script sign in again with a fresh token. This way the service knows the API integration or script is continually involved in re-authorizing the application. If you create your own integration or script using Incydr APIs, to ensure a fresh token for your API requests, write your scripting so that the API client ID and secret are submitted for a new token as part of the request.

API clients in the Incydr console

To view API clients:

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

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	Last modified	The last time the API client was edited. This makes it easier to track when secrets were last updated, which can help you manage secret rotation.
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 > Reset API secret.)
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:

1. Click Actions 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 . 

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 modified	The last time the API client was edited. This makes it easier to track when secrets were last updated, which can help you manage secret rotation.
d	Last redeemed	The last time the API client's ID and secret were submitted to obtain authentication.
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 > Reset API secret.)
f	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 Incydr 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 Incydr 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.
• Device Read access is required for any API client used to download exfiltrated files.

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 Incydr console.
2. Select Administration > Integrations > API Clients.
3. Click Create new API client.
   The Create new API client dialog appears. 
   
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.
   
7. 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 Incydr cloud instance (see Request URLs in the Incydr Developer Portal).
8. Click Done.
   The new API client is displayed in the Incydr 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 Incydr 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 Incydr Developer Portal.

Edit an API client

1. Sign in to the Incydr console.
2. Select Administration > Integrations > API Clients.
3. Click Actions on the API client to edit.
4. Select Edit API client.
   The Edit API client dialog appears. 
    
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 Incydr console.
2. Select Administration > Integrations > API Clients.
3. Click Actions on the API client whose secret you want to reset.
4. Select Reset API secret.
   The Reset API secret dialog appears.
   
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.
   
6. 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.
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 Incydr APIs, submit the client ID and with the Auth API to obtain an authentication token to use in your requests (see Authentication in the Incydr 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 Incydr console.
2. Select Administration > Integrations > API Clients.
3. Click Actions on the API client to delete.
4. Select Delete API client.
   The Delete API client dialog appears.
   
5. Click Delete.
   The API client is deleted.

Related topics

• Authentication in the Incydr Developer Portal
• Incydr integrations resources