Managing API tokens

Note

  • We've renamed Microsoft Cloud App Security. It's now called Microsoft Defender for Cloud Apps. In the coming weeks, we'll update the screenshots and instructions here and in related pages. For more information about the change, see this announcement. To learn more about the recent renaming of Microsoft security services, see the Microsoft Ignite Security blog.

  • Microsoft Defender for Cloud Apps is now part of Microsoft 365 Defender. The Microsoft 365 Defender portal allows security admins to perform their security tasks in one location. This will simplify workflows, and add the functionality of the other Microsoft 365 Defender services. Microsoft 365 Defender will be the home for monitoring and managing security across your Microsoft identities, data, devices, apps, and infrastructure. For more information about these changes, see Microsoft Defender for Cloud Apps in Microsoft 365 Defender.

Defender for Cloud Apps exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Defender for Cloud Apps capabilities.

To access the Defender for Cloud Apps API, you have to create an API token and use it in your software to connect to the API. This token will be included in the header when Defender for Cloud Apps makes API requests.

The API access requires OAuth2.0 authentication. For more information, see OAuth 2.0 Authorization Code Flow.

In general, you’ll need to take the following steps to use the APIs:

  • Create an Azure Active Directory (Azure AD) application
  • Get an access token using this application
  • Use the token to access the Defender for Cloud Apps API

You can access the Defender for Cloud Apps API with Application Context or User Context.

Note

The legacy method of accessing the Defender for Cloud Apps API is still supported. However, it is on a deprecation path, so we recommend using the methods described on this page.

Used by apps that run without a signed-in user present. For example, apps that run as background services or daemons.

Steps that need to be taken to access Defender for Cloud Apps API with application context:

  1. Create an Azure AD Web-Application.
  2. Assign the desired permission to the application. For example, Read Alerts or Upload Discovery Report.
  3. Create a key for this application.
  4. Get the token using the application with its key.
  5. Use the token to access the Defender for Cloud Apps API.

For more information, see Get access with application context.

User context

Used to perform actions in the API on behalf of a user.

Steps to take to access the Defender for Cloud Apps API with application context:

  1. Create an Azure AD Native-Application.
  2. Assign the desired permission to the application. For example, Read Alerts or Upload Discovery Report.
  3. Get the token using the application with user credentials.
  4. Use the token to access the Defender for Cloud Apps API.

For more information, see Get access with user context.