Topics
Authorization
Before using all Chrome Enterprise Core APIs, you will need to enable the Admin SDK API (if not already enabled) in the Google Developer Console by following this link and selecting the project on which you wish to enable the API.
From there, you have 2 choices of obtaining a token to access the API:
- Oauth2.0 with impersonation using a service account (Read below the section "Authorize With Impersonation")
- 3-legged Oauth2.0 without impersonation (You can authorize your requests following the Oauth2 Guideline)
The following scopes are needed to authorize your access to the Chrome Enterprise Core API:
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly
or
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers
Authorize With Impersonation
To us a service account for impersonation, you need to:
- Create a service account and have the necessary service account keys for this service account. You can follow this for creating a service account and getting the service account keys.
- The client ID for this service account will need to be authorized for the OAuth scopes listed above. To do this, you must go to the Admin Console under Security -> API controls -> Manage domain wide delegation. You will then add a new client. On this dialog, the Client ID corresponds to the Unique ID of your service account.
With the service account keys, you will need to use the Google API Client Libraries of your preferred language to request an OAuth Access Token for your service account.
Furthermore, the OAuth Token request will also need to impersonate an admin user in your domain when requesting the OAuth Token.
As an example, here is some sample code using the Java API Client Libraries to retrieve the oauth token.
package takeout.api.credentials;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
public final class ApiRequestHelper {
public static String getAccessToken(
String serviceAccountKeyFilePath, String adminUserToImpersonate, Collection<String> scopes)
throws IOException {
InputStream is = new FileInputStream(serviceAccountKeyFilePath);
GoogleCredential credential =
GoogleCredential.fromStream(is).toBuilder()
.setServiceAccountScopes(scopes)
.setServiceAccountUser(adminUserToImpersonate)
.build();
if (!credential.refreshToken()) {
throw new RuntimeException(
String.format(
"Failed to fetch refresh token for service account defined in '%s' for user '%s' and"
+ " scopes '%s'",
serviceAccountKeyFilePath, adminUserToImpersonate, String.join(",", scopes)));
}
return credential.getAccessToken();
}
public static void printUsage() {
System.out.println(
"Usage: get_access_token <service account key file> <admin user> [<scope,scope>]");
}
public static void main(String[] args) throws Exception {
if (args.length < 2) {
printUsage();
return;
}
String scopes =
"https://www.googleapis.com/auth/admin.directory.device.chromebrowsers";
if (args.length >= 3) {
scopes = args[2];
}
System.out.println(
getAccessToken(args[0], args[1], new ArrayList<String>(Arrays.asList(scopes.split(",")))));
}
private ApiRequestHelper() {}
}
Using this sample code, you will be able to retrieve an access token which you can use to call the API. For example, if your key file is stored in /home/private_key.json and the admin account you want to use to make the request is [email protected] then you would run the exetuable with the following arguments:
ApiRequestHelper /home/private_key.json [email protected]
Note: The admin email used is not the e-mail of your service account (which is in the form <project-name>-<id>@<project-name>.iam.gserviceaccount.com).
Chrome browser
Chrome browsers enrolled in Chrome Enterprise Core.
Resource Representation
The following JSON template is used for Chromebrowser resources in the Directory API:
{
"kind": "admin#directory#browserdevice",
"deviceId": string,
"osPlatform": string,
"osPlatformVersion": string,
"osArchitecture":string,
"osVersion": string,
"machineName": string,
"annotatedLocation": string,
"annotatedUser": string,
"annotatedAssetId": string,
"annotatedNotes": string,
"lastPolicyFetchTime": dateTime,
"lastRegistrationTime": dateTime,
"lastActivityTime":dateTime,
"lastStatusReportTime":dateTime,
"virtualDeviceId": string,
"serialNumber": string,
"orgUnitPath": string,
"extensionCount":int,
"policyCount": int,
"safeBrowsingClickThroughCount": int,
"lastDeviceUser": string,
"browserVersions": [string],
"lastDeviceUsers":[
"userName": strin,
"lastStatusReportTime":dateTime,
]
"machinePolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"browsers": [
"browserVersion": string,
"channel": string,
"lastStatusReportTime": dateTime,
"lastPolicyFetchTime": dateTime,
"executablePath": string,
"installedBrowserVersion": string,
"plugins":[
"name": string,
"description": string,
"fileame" string,
]
"profiles": [
"name": string,
"id": string,
"lastStatusReportTime": dateTime,
"lastPolicyFectchTime": dateTime,
"safeBrowsingWarnings": int,
"safeBrowsingWarningsClickThrough": int,
"chromeSignedinUserEmail": string,
"extensionPolicies": [
"extensionId": string,
"extensionName": string,
"policies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
]
"extensions": [
"extensionId": string,
"version": string,
"permissions": [string],
"name": string,
"description":string,
"appType": string,
"homepageUrl": string,
"installType": string,
"configuredAppPolicy": string,
"disabled": boolean,
"icons": [
"size": int,
"url": string,
]
]
"userPolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"safeBrowsingWarningsResetTime": string
]
}
Calling the API
Retrieve all Chrome browser devices for an account
Limitation: The nextPageToken returned by the listing request has a 1 hour lifetime. If your listing request has a large number of Chrome browser devices, your page token may expire before you can finish listing all the devices. In this case you may want to apply a filter to your listing request in order to reduce the number of devices returned by the query. Typically, filtering by OU is a good way to reduce the number of results.
To return a list of all Chrome browser devices assigned to an account, use the following GET request and include the authorization described in Authorization. For readability, this code sample has line returns:
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers?projection={FULL|BASIC}&query={query string}&orderBy={orderBy
category}&sortOrder={ASCENDING|DESCENDING}&pageToken={token for next results
page, if applicable &maxResults=max number of results per page}
- The customerId is a unique identifier of the customer's Google account.
- When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
The following is a reference of all query string parameters that can be used in the request:
| Parameter | Type | Description |
|---|---|---|
| maxResults | integer | Maximum number of results to return. Default, and maximum, is 100. |
| orderBy | string | Chrome browser device property to use for sorting results. |
| Acceptable values for are | ||
| "id" - The ID of the device with Chrome browser installed. | ||
| "last_sync" - The date and time the Chrome browser device was either last registered, last synchronized with policy settings, or uploaded a report. | ||
| "machine_name" - The name of the machine associated with the device. | ||
| "extension_count" - Chrome browser device’s total number of extensions reported. | ||
| "policy_count" - Chrome browser device’s total number of policies reported. | ||
| "os_version" - OS of the device on which Chrome browser is installed. | ||
| "last_signed_in_user" - Chrome browser device’s last signed in user. | ||
| "annotated_user" - Chrome browser device user as annotated by the administrator. | ||
| "annotated_location" - Chrome browser device location as annotated by the administrator. | ||
| "annotated_asset_id" - Chrome browser device asset id as annotated by the administrator. | ||
| "notes" - Chrome browser device notes as annotated by the administrator. | ||
| "browser_version_channel" - The last Chrome version and channel reported by the device. | ||
| "org_unit" - The Organizational Unit that the device is under. | ||
| "enrollment_date" - The enrollment date of the device. | ||
| "save_browsing_clickthrough" - Number of Safe Browsing click throughs this device has reported. | ||
| "platform_major_version" - OS type and major version e.g.(Windows 10).: | ||
| "last_activity" - The last activity time for the device.: | ||
| "browser_version_sortable" - The oldest browser version installed on the device.: | ||
| "os_version_sortable" - OS type and full version.: | ||
| orgUnitPath | string | The full path of the organizational unit or its unique ID. |
| groupId | string | The full resource name of the group in the form groups/{group} or its unique ID. |
| pageToken | string | The pageToken query parameter is used to request the next page of query results. The follow-on request's pageToken query parameter is the nextPageToken from your previous response. |
| projection | string | Restrict information returned to a set of selected fields. |
| Acceptable values are: | ||
| "BASIC" - Includes only the basic metadata fields (i.e., the ones found in the columns of the admin console browser list as enumerated above) | ||
| "FULL" - Includes all metadata fields (as enumerated above) | ||
| query | string | Search string using the list page query language described in the section below (Filter Query Language). |
| sortOrder | string | Whether to return results in ascending or descending order. Must be used with the orderBy parameter. |
| Acceptable values are: | ||
| "ASCENDING" - Ascending order. | ||
| "DESCENDING" - Descending order. |
Example: Filter devices by machine name
This first example searches for specific machine name by using query=machine_name:CLIENT2012. The response contains a single Chrome browsers resource, where the machineName is help desk:
JSON request
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers?projection=BASIC&query=machine_name:CLIENT2012&orderBy=status
&sortOrder=ASCENDING&maxResults=100
JSON response
A successful request returns an HTTP 200 status code. Along with a list of browsers devices that match your query paramaters:
{
"kind": "directory#browserdevices",
"browsers": [
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19505",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-04T00:29:17.484Z",
"lastActivityTime": "2019-11-04T00:29:17.484Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
},
],
"nextPageToken": "abcdefghijkl123"
}
Retrieve a Chrome browser device
To retrieve a Chrome browser device's properties, use the following GET request and include the authorization described in Authorize requests. For readability, this code sample has line returns:
GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/deviceId?projection={FULL|BASIC}
- The customerId is a unique identifier of the customer's Google account.
- When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
- The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome browser devices operation. For the query strings, request, and response properties, see the API Reference.
The following is a reference of all query string parameters that can be used in the request:
| Parameter | Type | Description |
|---|---|---|
| deviceId | string | The unique ID of the device. The deviceIds are returned in the response from the browsersdevices.list method. Note: This parameter is required. |
| projection | string | Determines whether the response contains the full list of properties or only a subset. |
| Acceptable values are: | ||
| "BASIC": Includes only the basic metadata fields (i.e., the ones found in the columns of the admin console browsers list as enumerated above) | ||
| "FULL": Includes all metadata fields (as enumerated above) |
Example
JSON request
An example request. For readability, this code sample has line returns:
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/deviceId?projection=basic
JSON response
A successful request returns an HTTP 200 status code. Along with the status code, the response returns the Chrome browser device properties:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"deviceIdentifiersHistory": {
"records": [
{
"identifiers": {
"machineName": "CLIENT2012",
"serialNumber": "ABCD1234567890" },
"firstRecordTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z"}
],
“has_device_id_collision”: “false”
}
}
Filter query language
When using the "query" parameter in a list request, every term in the query must be matched in a specific browser device in order to be valid. If you specify no operators (fields) in the query then the search will find a browser that has all the specified terms across all internally indexed text fields. For example if your query is: "query=machine 73", this will return a browser that has both the term "machine" and "73" in all the fields which could be returned in a browser device like the following:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "machine_name",
"browser_versions": [
"73.0.0.0",
],
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
}
Note 1: Matching occurs on word boundaries (any punctuation or space) so that you would not be able to do partial matches on words. In the above example you would not be able to do query='mach 73'.
Note 2: Word matching is case insensitive so that a query with "machine" will match both "Machine" as well as "machine".
You can specify the following fields to target your search to specific fields (Note: although the query words are case insensitive, the field names are case sensitive).
| Field | Description |
|---|---|
| machine_name | The machine name for the Chrome browser device. |
| os_platform | The OS platform for the Chrome browser device. (e.g. Windows) |
| arch | The CPU architecture for the Chrome browser device. (e.g. x86_64) |
| os_version | The OS version for the chrome browser device. (e.g. 10.0.16299.904) |
| location | The annotated location for the Chrome browser device. |
| user | The annotated user for the Chrome browser device. |
| asset_id | The annotated asset ID for the Chrome browser device. |
| note | The annotated note for the Chrome browser device. |
| register | The registration time for the Chrome browser device. |
| os | The combine OS platform and major OS version for the Chrome browser device (e.g. "Windows 10") |
| browser_version | A reported Chrome browser installed on the Chrome browser device (e.g. 73) |
| enrollment_token | The enrollment token used to register the Chrome browser device. |
| report | The last report time for the Chrome browser device |
| sync | The last policy sync time for the Chrome browser device. |
| num_extensions | The number of extensions reported by the Chrome browser device. |
| num_policies | The number of policies reported by the Chrome browser device. |
| machine_user | The last reported user of the Chrome browser device. |
| last_activity | The last time the Chrome browser device has shown activity (policy fetch or reporting). |
| has_device_id_collision | Device ID is shared by multiple machines that Chrome Browser identifies as the same machine. Supported values are true and false. |
For fields that accept time (register, report, sync, last_activity) the time format is YYYY-MM-DDThh:mm:ss (e.g. 2020-01-01T12:00:00). You may also specify open or closed ranges for the time:
|
Form |
Meaning |
Examples |
|
datetime |
exactly on the given date or time |
2011-03-23 2011-04-26T14:23:05 |
|
datetime..datetime |
within (inclusive) the given interval of date or time |
2011-03-23..2011-04-26 |
|
datetime.. |
on or after the given date or time |
2011-04-26T14:23:05.. |
|
..datetime |
on or before the given date or time |
..2011-04-26T14:23:05 |
Example filter queries
Note 1: All provided examples use the 'query' parameter in the request. They parameter value must be properly escaped in the URL (i.e. to escape spaces with multi condition requests).
Note 2: All queries can further be filtered to a particular Organizational Unit by adding the 'orgUnitPath' query parameter to the request.
- Find all devices with machine name that contain a word:
machine_name:LIX
- Find all devices with machine name that contain a word that were registered after a certain date:
machine_name:LIX register:2011-04-26..
Find all devices with machine name that contain a word that were registered before a certain date:machine_name:LIX register:..2011-04-26
Currently unsupported queries:
- Find all devices that have less than a certain number of extensions installed (range queries for numerical values is not supported).
- Find all devices that have a machine name that contains one of two possible words (using OR in queries).
Update a Chrome browser device
To update the annotated fields of a Chrome browser devices assigned to an account, use the following PUT request and include the access token obtained by following the "Authorization" section.
PUT
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/{deviceId}
- The customerId is a unique identifier of the customer's Google account.
- When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
- The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome browser devices operation. For the query strings, request, and response properties, see the API Reference.
The following is a reference of all payload parameters that can be used in the request:
| Parameter | Required | Type | Description |
|---|---|---|---|
| deviceId | required | string | The unique ID of the device. The deviceIds are returned in the response from the browsersdevices.list method. Note: This parameter is required. |
| annotatedUser | optional | string | User of the device as annotated by the administrator. |
| annotatedLocation | optional | string |
Address or location of the device as annotated by the administrator. |
| annotatedNotes | optional | string | Notes about this device as annotated by the administrator |
| annotatedAssetId | optional | string |
Asset identifier as annotated by the administrator or specified during enrollment. |
Example
JSON request
An example request. For readability, this code sample has line returns:
PUT https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
{
"deviceId": "device_id_value",
"annotatedUser": "user 1"
}
JSON response
A successful request returns an HTTP 200 status code. Along with the status code, the response returns the Chrome browser device properties:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"annotatedUser": "user 1"
}
Delete a Chrome browser device
To delete a Chrome browser devices assigned to an account, use the following DELETE request and include the access token obtained by following the "Authorization" section.
DELETE
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices
chromebrowsers/{deviceId}
- The customerId is a unique identifier of the customer's Google account.
- When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
- The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome devices operation. For the query strings, request, and response properties, see the API Reference.
Example
An example request:
DELETE https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
JSON response
A successful request returns an HTTP 200 status code.
Move a Chrome browser device between organizational units
To move Chrome browser devices assigned to an account from one organization unit to another, use the following POST request and include the access token obtained by following the "Authorization" section.
POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices/chromebrowsers/moveChromeBrowsersToOu
- The customerId is a unique identifier of the customer's Google account.
- When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
The following is a reference of all payload parameters that can be used in the request:
| Parameter | Type | Description |
|---|---|---|
| resource_ids | List of string |
List of unique device IDs of Chrome browser devices to move. A maximum of 600 browsers may be moved per request. |
| org_unit_path | string |
Destination organization unit to move devices to. Full path of the organizational unit or its ID prefixed with "id:" |
Example
An example request.
POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/moveChromeBrowsersToOu
{
"org_unit_path": "/new-path",
"resource_ids": ["device_id_value_1","device_id_value_2"],
}
JSON response
A successful request returns an HTTP 200 status code.