Enterprise Recon v1 API

Data Classification with MIP

PRO This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your ER2 license, please contact Ground Labs Licensing. See Subscription License for more information.

Use this set of APIs to configure the settings for Data Classification with Microsoft Information Protection (MIP), and perform manual classification operations on sensitive data locations. See Data Classification with MIP for more details about using the feature.

Enable Data Classification with MIP

Enable (On) the Data Classification with MIP feature. MIP feature state must be enabled=true before any MIP credentials can be configured to perform classification actions.

Request

POST

https://er-master:8339/v1/classification/mip/enable

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
POST /v1/classification/mip/enable
Accept: application/json
cURL 
curl --request POST 'https://er-master:8339/v1/classification/mip/enable' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
message

string

Terms regarding the use of the Data Classification with MIP feature in ER2.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "message": "Microsoft Information Protection ('MIP') helps to discover, classify, and protect sensitive information wherever it lives or travels ('MIP Classification Functions'). By choosing to connect Enterprise Recon ('ER') to MIP, you are also agreeing to send error and performance data, including information about the configuration of your software like the software you are currently running and your IP address ('Data'), to Microsoft over the internet. Microsoft uses this Data to provide and improve the quality, security and integrity of Microsoft products and services. For more information on how Microsoft uses this Data, please visit https://privacy.microsoft.com/en-us/privacystatement. When turned off, the MIP Classification Functions will not be available through ER."
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Disable Data Classification with MIP

Disable (Off) the Data Classification with MIP feature. MIP feature state must be enabled=true before any MIP credentials can be configured to perform classification actions.

Request

POST

https://er-master:8339/v1/classification/mip/disable

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Not applicable

Request Samples

HTTP 
POST /v1/classification/mip/disable
Accept: application/json
cURL 
curl --request POST 'https://er-master:8339/v1/classification/mip/disable' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Samples

204 No Content
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Get Status of Data Classification with MIP

Check the status of the Data Classification with MIP feature. MIP feature state must be enabled=true before any MIP credentials can be configured to perform classification actions.

Request

GET

https://er-master:8339/v1/classification/mip

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Classification

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/classification/mip
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/classification/mip' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
enabled

boolean

enum: true false

 Returns true if the Data Classification with MIP feature is enabled.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "enabled": true
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Get Agents for Data Classification with MIP

Retrieve a list of available (online) Windows Agents to be used for the Data Classification with MIP features. All available Windows Agents for the Master Server instance will be returned, regardless of the Agent version. The Data Classification with MIP feature must be enabled for this API call to be successful. See Enable Data Classification with MIP for more information.

Request

GET

https://er-master:8339/v1/classification/mip/agents

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/classification/mip/agents
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/classification/mip/agents' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
[agent_id]

string <array>

List of Windows Agent IDs.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  "11339246050428803009",
  "3068695012964441453",
  "11361689295684005272",
  "16572029725285027484"
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if the Data Classification with MIP feature state is disabled.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied. Please ensure that Data Classification with MIP feature is enabled."
}

Retrieve Credentials for Data Classification with MIP

Retrieve the currently configured credentials for Data Classification with MIP. The Data Classification with MIP feature must be enabled for this API call to be successful. See Enable Data Classification with MIP for more information.

Request

GET

https://er-master:8339/v1/classification/mip/credentials

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/classification/mip/credentials
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/classification/mip/credentials' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
login_id

string

example: admin@example.onmicrosoft.com

 User name of a Microsoft 365 user. Sensitivity labels that can be retrieved by ER2 depends on the labels that are available in label policies published to the user.
app_id

string

example: myAppId-example-enterpriserecon-1234

 The Application (client) ID value obtained when generating a Client ID.
agent_id

string

example: 455572488728221120

 ID of a Windows Agent with direct internet access. The selected Windows Agent is used to retrieve classification labels that are published to the user specified in the login_id field.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "login_id": "admin@example.onmicrosoft.com",
  "app_id": "myAppId-example-enterpriserecon-1234",
  "agent_id": "455572488728221120"
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if the Data Classification with MIP feature state is disabled.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied. Please ensure that Data Classification with MIP feature is enabled."
}
404 Not Found

Returned if the Data Classification with MIP feature state is enabled but no MIP credentials have been configured.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found. Please ensure that credentials for Data Classification with MIP have been configured."
}

Add or Update Credentials for Data Classification with MIP

Add or update the currently configured credentials for Data Classification with MIP. MIP credentials will only be saved if there are no credentials-related errors. The Data Classification with MIP feature must be enabled for this API call to be successful. See Enable Data Classification with MIP for more information.

Request

PUT

https://er-master:8339/v1/classification/mip/credentials

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
login_id

string

example: admin@example.onmicrosoft.com

 User name of a Microsoft 365 user. Sensitivity labels that can be retrieved by ER2 depends on the labels that are available in label policies published to the user.
app_id

string

example: myAppId-example-enterpriserecon-1234

 The Application (client) ID value obtained when generating a Client ID.
app_secret

string

example: myAppSecretKey-enterpriserecon-123

 Client Secret key value obtained when generating a Client Secret Key. This parameter must be provided during the initial configuration of the credentials. However, this field will not be cleared if it is not provided when updating the credential set.
password

string

Password of the user specified in the login_id field. This parameter must be provided during the initial configuration of the credentials. However, this field will not be cleared if it is not provided when updating the credential set.
agent_id

string

example: 455572488728221120

 ID of a Windows Agent with direct internet access. The selected Windows Agent will be used to retrieve classification labels that are published to the user specified in the login_id field.

Request Samples

HTTP 
PUT /v1/classification/mip/credentials
{
  "login_id": "admin@example.onmicrosoft.com",
  "app_id": "myAppId-example-enterpriserecon-1234",
  "app_secret": "myAppSecretKey-enterpriserecon-123",
  "password": "@dminPassw0rd123",
  "agent_id": "455572488728221120"
}
cURL 
curl --request PUT 'https://er-master:8339/v1/classification/mip/credentials' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "login_id": "admin@example.onmicrosoft.com",
  "app_id": "myAppId-example-enterpriserecon-1234",
  "app_secret": "myAppSecretKey-enterpriserecon-123",
  "password": "@dminPassw0rd123",
  "agent_id": "455572488728221120"
}'

Response Samples

204 No Content
401 Unauthorized

Returned if the provided MIP credentials are invalid and cannot be authenticated successfully.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to retrieve a list of MIP labels. Error: Client application failed to provide authentication token for HTTP request."
}

Returned if the MIP runtime library is not installed on the host machine of the selected proxy agent, or if the selected proxy agent version/platform does not support Data Classification with MIP.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Please ensure that the required MIP runtime package is installed on the agent host machine. Error: <>"
}

Returned if the selected agent is not available, or the provided agent ID is invalid.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to retrieve a list of MIP labels. Error: Invalid Agent UID"
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if the Data Classification with MIP feature state is disabled.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied. Please ensure that Data Classification with MIP feature is enabled."
}
404 Not Found

Returned if the Data Classification with MIP feature state is enabled but no MIP credentials have been configured. This occurs when adding the credentials for the first time without providing the application secret and user password.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found. Please ensure that credentials for Data Classification with MIP have been configured."
}

Returned if there are no MIP labels or policies configured for the login ID used for authentication.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to retrieve MIP labels. Users will not be able to classify locations until a policy is created on MIP Cloud."
}

Retrieve List of MIP Labels

Retrieve a list of MIP labels published to the user configured for the Data Classification with MIP credentials. The Data Classification with MIP feature must be enabled for this API call to be successful. See Enable Data Classification with MIP for more information.

Request

GET

https://er-master:8339/v1/classification/mip/labels

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Classification

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Query Parameters

Parameter Data Type Description
refresh

boolean

default: false

enum: true false

 If refresh=true, ER2 retrieves an updated list of labels from Microsoft Information Protection to refresh the datastore information. If refresh=false or is not specified in the request, ER2 only retrieves the labels stored in the datastore (no probing required).

Request Samples

HTTP 
GET /v1/classification/mip/labels?refresh=true
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/classification/mip/labels?refresh=true' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
id

string

MIP label ID.
label

string

MIP sensitivity label.
sensitivity

string

The sensitivity level or order for the label.
requires_file_protection

boolean

enum: true false

 Returns true if the label requires the file to be protected or encrypted in order to be classified.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "abcdefgh-1234-ijkl-5678-mnopqrst9012",
    "label": "Sensitivity Label 1",
    "sensitivity": 2,
    "requires_file_protection": false
  },
  ...
  {
    "id": "abcd1234-efgh-ijkl-5678-mnopqrst9012",
    "label": "Sensitivity Label 2 - Encrypt",
    "sensitivity": 7,
    "requires_file_protection": true
  }
]
401 Unauthorized

Returned if the provided MIP credentials are invalid and cannot be authenticated successfully.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to retrieve a list of MIP labels. Error: Client application failed to provide authentication token for HTTP request."
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if the Data Classification with MIP feature state is disabled.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied. Please ensure that Data Classification with MIP feature is enabled."
}
404 Not Found

Returned if there are no MIP labels or policies configured for the login ID used for authentication.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to retrieve MIP labels. Users will not be able to classify locations until a policy is created on MIP Cloud."
}

Apply or Remove Classification for Match Location

Manually apply or remove the MIP Classification label for a match location. The Data Classification with MIP feature must be enabled for this API call to be successful. See Enable Data Classification with MIP for more information.

Request

POST

https://er-master:8339/v1/targets/<target_id>/locations/<location_id>/classification/mip/label

Authorization

Basic Authentication

User Permissions

  • Pre-requisite: Allow API Access
  • Global permissions: Global Admin, Classification Admin
  • Resource permissions: Classification

Path Parameters

Parameter Data Type Description
target_id

string

Specify the Target ID for the match object to classify. target_id is the targets->id response item from the /v1/groups/all endpoint.
location_id

string

Specify the location ID for the match object to classify. location_id is the targets->locations->id response item from the /v1/groups/all endpoint.

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
label_id

string

example: abcdefgh-1234-ijkl-5678-mnopqrst9012

 ID of the MIP sensitivity label to apply to the match location. label_id is the id response item from the /v1/classification/mip/labels endpoint. Leaving the label_id field blank will remove the sensitivity label for the match location.
path

string

example: D:\\Folder-A\\MyFile.docx

 Path to the match object. path is the path response item from the /v1/targets/<target_id>/matchobjects endpoint.
sign_off

string

example: admin

 User signing off on the classification action.
reason

string

example: Applying new MIP label.

 Reason for performing the classification action.

Request Samples

HTTP 
POST /v1/targets/4759598330602895744/locations/9832457584012239212/classification/mip/label
{
  "label_id": "abcdefgh-1234-ijkl-5678-mnopqrst9012",
  "path": "D:\\Folder-A\\MyFile.docx",
  "sign_off": "Admin",
  "reason": "Apply label 1"
}
cURL 
curl --request POST 'https://er-master:8339/v1/targets/4759598330602895744/locations/9832457584012239212/classification/mip/label' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label_id": "abcdefgh-1234-ijkl-5678-mnopqrst9012",
  "path": "D:\\Folder-A\\MyFile.docx",
  "sign_off": "Admin",
  "reason": "Apply label 1"
}'

Response Schema

202 Accepted
Response Item Data Type Description
path

string

MIP label ID.
job_id

number

MIP sensitivity label.

Response Samples

202 Accepted 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "path": "D:\\Folder-A\\MyFile.docx",
    "job_id": 1623394318
  }
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}
404 Not Found

Returned if an invalid Target ID or location ID is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found."
}

Returned if an invalid label_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'label_id' does not exist."
}