Code samples

The requests below illustrate policy management with the Policy API. Before you begin, make sure you review the Chrome Policy API Overview for a high-level summary of this API's features.

All the requests presented below use the following variables:

• $TOKEN - OAuth 2 token
• $CUSTOMER - Id of the customer or literal my_customer

List schemas for printer policies

To list schemas that only concern policies for printers, we will apply filter parameter to the Schema Service list request. You may control pagination of the result using pageSize and pageToken parameters.

Request

  curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=chrome.printers&pageSize=2"

Response

{
  "policySchemas": [
    {
      "name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForUsers",
      "policyDescription": "Allows a printer for users in a given organization.",
      "additionalTargetKeyNames": [
        {
          "key": "printer_id",
          "keyDescription": "Id of printer as visible in Admin SDK printers API."
        }
      ],
      "definition": {
        "messageType": [
          {
            "name": "AllowForUsers",
            "field": [
              {
                "name": "allowForUsers",
                "number": 1,
                "label": "LABEL_OPTIONAL",
                "type": "TYPE_BOOL"
              }
            ]
          }
        ]
      },
      "fieldDescriptions": [
        {
          "field": "allowForUsers",
          "description": "Controls whether a printer is allowed for users in a given organization."
        }
      ],
      "schemaName": "chrome.printers.AllowForUsers"
    },
    {
      "name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForDevices",
      "policyDescription": "Allows a printer for devices in a given organization.",
      "additionalTargetKeyNames": [
        {
          "key": "printer_id",
          "keyDescription": "Id of printer as visible in Admin SDK printers API."
        }
      ],
      "definition": {
        "messageType": [
          {
            "name": "AllowForDevices",
            "field": [
              {
                "name": "allowForDevices",
                "number": 1,
                "label": "LABEL_OPTIONAL",
                "type": "TYPE_BOOL"
              }
            ]
          }
        ]
      },
      "fieldDescriptions": [
        {
          "field": "allowForDevices",
          "description": "Controls whether a printer is allowed for devices in a given organization."
        }
      ],
      "schemaName": "chrome.printers.AllowForDevices"
    }
  ],
  "nextPageToken": "AEbDN_obE8A98T8YhIeU9VCIZhEBylLBwZRQpGu_DUug-mU4bnzcDx30UnO2xMuuImvfVpmeuXRF6VhJ4OmZpZ4H6EaRvu2qMOPxVN_u"
}

Search for schemas

You may create complex search queries using filter= parameter in the Schema Service list request. For example if you want to search for schemas that have the word "printer" in the name and word "devices" in description you may apply the following value to the filter name=printers AND description=devices.

Learn how to list policy schemas.

Request

  curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=name=printers%20AND%20description=devices"

Response

{
  "policySchemas": [
    {
      "name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForDevices",
      "policyDescription": "Allows a printer for devices in a given organization.",
      "additionalTargetKeyNames": [
        {
          "key": "printer_id",
          "keyDescription": "Id of printer as visible in Admin SDK printers API."
        }
      ],
      "definition": {
        "messageType": [
          {
            "name": "AllowForDevices",
            "field": [
              {
                "name": "allowForDevices",
                "number": 1,
                "label": "LABEL_OPTIONAL",
                "type": "TYPE_BOOL"
              }
            ]
          }
        ]
      },
      "fieldDescriptions": [
        {
          "field": "allowForDevices",
          "description": "Controls whether a printer is allowed for devices in a given organization."
        }
      ],
      "schemaName": "chrome.printers.AllowForDevices"
    }
  ]
}

Get a particular schema

In the above result, we see a list of supported policy schemas. Each schema has a name field that identifies the schema. In the future, once you know the schema name, you may read the particular schema directly by referring to the schema name in the request URL.

Let's see an example for chrome.printers.AllowForUsers schema.

Request

  curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas/chrome.printers.AllowForUsers"

Response

{
  "name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForUsers",
  "policyDescription": "Allows a printer for users in a given organization.",
  "additionalTargetKeyNames": [
    {
      "key": "printer_id",
      "keyDescription": "Id of printer as visible in Admin SDK printers API."
    }
  ],
  "definition": {
    "messageType": [
      {
        "name": "AllowForUsers",
        "field": [
          {
            "name": "allowForUsers",
            "number": 1,
            "label": "LABEL_OPTIONAL",
            "type": "TYPE_BOOL"
          }
        ]
      }
    ]
  },
  "fieldDescriptions": [
    {
      "field": "allowForUsers",
      "description": "Controls whether a printer is allowed for users in a given organization."
    }
  ],
  "schemaName": "chrome.printers.AllowForUsers"
}

Above policy schema response describes the schema of chrome.printers.AllowForUsers policy. Notice field additionalTargetKeyNames. This field explains that the policy requires extra keys/values to be provided when dealing with this policy. In particular, for this policy we always need to provide the identifier of a printer.

Read a policy value

Let's read a policy chrome.printers.AllowForUsers for a particular printer. Notice using field additionalTargetKeys to specify printer ID in the request.

You can read a policy from an Organizational Unit or from a Group.

In the response, notice the sourceKey field, which specifies which Organizational Unit or Group the value of the policy comes from. For Organizational Units, there are the following possibilities:

• If source Organizational Unit is the same as Organizational Unit given in a request, it means the policy is locally applied in this Organizational Unit.
• If source Organizational Unit is different than Organizational Unit given in a request, it means the policy is inherited from the source Organizational Unit.
• If no sourceKey is present, or the response is empty, it means the policy is not set for the customer, and it has default system value.

For Groups, the sourceKey will always be the same as the Group that was specified in the request.

The following example is for an Organizational Unit. A Group request would be the same except for the targetResource, which would have "groups/" instead of "orgunits/" before the id.

Request

  curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        policyTargetKey: {
          targetResource: "orgunits/04fatzly4jbjho9",
          additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
        },
        policySchemaFilter: "chrome.printers.AllowForDevices"
    }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies:resolve"

Response

{
  "resolvedPolicies": [
    {
      "targetKey": {
        "targetResource": "orgunits/03ph8a2z1xdnme9"
        "additionalTargetKeys": {"printer_id":"0gjdgxs208tpef"}
      },
      "value": {
        "policySchema": "chrome.users.AllowForDevices",
        "value": {
          "allowForDevices": true
        }
      },
      "sourceKey": {
        "targetResource": "orgunits/03ph8a2z3qhz81k"
      }
    }
  ]
}

Note that all entities in the target resources can be fetched by omitting additionalTargetKeys from the request. For instance, if additionalTargetKeys were omitted from the above request, it would return all of the printers in the specified target resource.

Read multiple policies

Providing a schema namespace with an asterisk (e.g., chrome.printers.*) allows you to read values for all policies under this namespace in a particular Organizational Unit or Group. Learn more about Policy Schemas.

The following example is for an Organizational Unit. A Group request would be the same except for the targetResource, which would have "groups/" instead of "orgunits/" before the id.

Request

  curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        policyTargetKey: {
          targetResource: "orgunits/04fatzly4jbjho9",
        },
        policySchemaFilter: "chrome.printers.*"
    }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies:resolve"

Response

{
  "resolvedPolicies": [
    {
      "targetKey": {
        "targetResource": "orgunits/04fatzly4jbjho9",
        "additionalTargetKeys": {
          "printer_id": "0gjdgxs0xd59y1"
        }
      },
      "value": {
        "policySchema": "chrome.printers.AllowForUsers",
        "value": {
          "allowForUsers": false
        }
      }
    },
    {
      "targetKey": {
        "targetResource": "orgunits/04fatzly4jbjho9",
        "additionalTargetKeys": {
          "printer_id": "0gjdgxs0xd59y1"
        }
      },
      "value": {
        "policySchema": "chrome.printers.AllowForDevices",
        "value": {
          "allowForDevices": false
        }
      }
    },
    //...
  ],
  "nextPageToken": "AEbDN_pFvDeGSbQDkvMxr4UA0Ew7UEUw8aJyw95VPs2en6YxMmFcWQ9OQQEIeSkjnWFCQNyz5GGoOKQGEd50e2z6WqvM2w7sQz6TMxVOBD_4NmEHRWtIJCYymeYXWHIrNH29Ezl1wkeyYBAOKnE="
}

Modify policy value

As seen in policy schema response, the policy chrome.printers.AllowForUsers has one field named allowForUsers. This field is of a boolean type. Example value of the policy could be either {allowForUsers: false} or {allowForUsers: true}. In this particular case, we have only one field, however other policies may contain multiple fields.

Note: Nullable fields support an explicit null state to force the default, instead of inheriting from the parent. Setting empty object "{}" as the value will set it to null.

In modify requests, we need to specify an updateMask. Update mask lists all of the fields we wish to modify. If policy was already locally applied in the Organizational Unit, then the fields that are not listed via update mask will remain untouched. If policy was not already locally applied in the Organizational Unit, and all the fields that are not listed via update mask will copy their values from the parent Organizational Unit when appropriate, and the whole policy will become locally applied.

The following examples are for an Organizational Unit. Group requests are the same except for the targetResource, which would have "groups/" instead of "orgunits/" before the id. Here we will disallow a printer 0gjdgxs208tpef for users in Organizational Unit ID 04fatzly4jbjho9:

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        requests: [{
                policyTargetKey: {
                        targetResource: "orgunits/04fatzly4jbjho9",
                        additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
                        },
                policyValue: {
                        policySchema: "chrome.printers.AllowForUsers",
                        value: {allowForUsers: false}
                        },
                updateMask: {paths: "allowForUsers"}
                }]
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"

Response

A successful response is empty.

{}

Multi-value fields like lists or arrays are marked with a "LABEL_REPEATED" label. To populate multi-value fields, use the following JSON array format: [value1, value2, value3, ...].

For example, to set sources urls for app and extension packages as "test1.com", "test2.com" and "test3.com", we need to send the following request:

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
        requests: [
          {
            policy_target_key: {
              target_resource: 'orgunits/03ph8a2z28rz85a'
            },
            updateMask: {
              paths: ['extensionInstallSources']
            },
            policy_value: {
              policy_schema: 'chrome.users.appsconfig.AppExtensionInstallSources', 
              value: {
                extensionInstallSources: ['test1.com', 'test2.com', 'test3.com']
              }
            }
          }
        ]
      }" \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"

Response

A successful response is empty.

{}

For all policies that contain NullableDuration fields, there are two versions. Original version only accepts string as input for NullableDuration and is now deprecated. Please use V2 version which replaces the duration type with a numeric input. For example, to set the maximum user session length as 10 minutes we need to send the following request:

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
        requests: [
          {
            policy_target_key: {
              target_resource: 'orgunits/03ph8a2z28rz85a'
            },
            updateMask: {
              paths: ['sessionDurationLimit']
            },
            policy_value: {
              policy_schema: 'chrome.users.SessionLengthV2',
              value: {
                sessionDurationLimit: {
                  duration: 10
                }
              }
            }
          }
        ]
      }" \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"

Response

A successful response is empty.

{}

Modify multiple policies at once

The batchModify method allows you to send multiple policy modifications at the same time. However, not all policies can be batched together. For more details, see Batch update policies.

Note: Modifying multiple policies at once in a single batchModify request is recommended to reduce the number of requests to the server. Learn more about Usage limits.

In this example we will be modifying, in the same request, two different policies (chrome.printers.AllowForDevices and chrome.printers.AllowForUsers) for the same printer.

The following example is for an Organizational Unit. A Group request would be the same except for the targetResource, which would have "groups/" instead of "orgunits/" before the id.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        requests: [{
                policyTargetKey: {
                        targetResource: "orgunits/04fatzly4jbjho9",
                        additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
                        },
                policyValue: {
                        policySchema: "chrome.printers.AllowForDevices",
                        value: {allowForDevices: true}
                        },
                updateMask: {paths: "allowForDevices"}
                },
                {
                policyTargetKey: {
                        targetResource: "orgunits/04fatzly4jbjho9",
                        additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
                        },
                policyValue: {
                        policySchema: "chrome.printers.AllowForUsers",
                        value: {allowForUsers: true}
                        },
                updateMask: {paths: "allowForUsers"}
                }]
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/C0202nabg/policies/orgunits:batchModify"

Response

A successful response is empty.

{}

Inherit a policy value in an Organizational Unit

The batchInherit method allows you to modify the status of policy in an Organizational Unit from "locally applied" to "inherited". Local values will be cleared, and the policy will inherit values from a parent Organizational Unit when applicable.

The batchInherit method also allows you to send multiple policy inherit requests at the same time. However, not all policies can be batched together. For more details, see Batch update policies.

Note: Modifying multiple policies at once in a single batchInherit request is recommended to reduce the number of requests to the server. Learn more about Usage limits.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        requests: [{
                policyTargetKey: {
                        targetResource: "orgunits/04fatzly12wd3ox",
                        additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
                        },
                policySchema: "chrome.printers.AllowForUsers"
                }]
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchInherit"

Response

A successful response is empty.

{}

Delete a policy value in a Group

The batchDelete method allows you to delete a policy from a Group. Local values will be cleared.

The batchDelete method also allows you to send multiple policy delete requests at the same time. However, not all policies can be batched together. For more details, see Batch update policies.

Note: Modifying multiple policies at once in a single batchDelete request is recommended to reduce the number of requests to the server. Learn more about Usage limits.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        requests: [{
                policyTargetKey: {
                        targetResource: "groups/04fatzly12wd3ox",
                        additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
                        },
                policySchema: "chrome.printers.AllowForUsers"
                }]
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:batchDelete"

Response

A successful response is empty.

{}

List the priority ordering for a Group

The listGroupPriorityOrdering method allows you to list the priority ordering of the Groups for an app.

The order of the Group IDs that are returned indicates the priority in which their settings will be applied for the app; later ids' policies will be overridden by policies whose ids are earlier in the list.

Note that Group priorities are higher than Organizational Unit priorities.

In this request, we are returning the priority ordering for the "exampleapp" Chrome User app.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        policyTargetKey: {
                additionalTargetKeys: {"app_id":"chrome:exampleapp"}
                },
        policyNamespace: 'chrome.users.apps'
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:listGroupPriorityOrdering"

Response

{
  "policyTargetKey": {
    "additionalTargetKeys": {
      "app_id": "chrome:exampleapp"
    }
  },
  "policyNamespace": "chrome.users.apps",
  "groupIds": [
    "03ep43zb2k1nodu",
    "01t3h5sf2k52kol",
    "03q5sasy2ihwnlz"
  ]
}

Update the priority ordering for a Group

The updateGroupPriorityOrdering method allows you to update the priority ordering of the Groups for an app.

The order of the Group IDs in the request indicates the priority in which their settings will be applied for the app; later ids' policies will be overridden by policies whose ids are earlier in the list. The request must include every Group ID that is currently applied on the app.

Note that Group priorities are higher than Organizational Unit priorities.

In this request, we are setting the priority ordering for the "exampleapp" Chrome User app.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        policyTargetKey: {
                additionalTargetKeys: {"app_id":"chrome:exampleapp"}
                },
        policyNamespace: 'chrome.users.apps',
        groupIds: ['03ep43zb2k1nodu', '01t3h5sf2k52kol', '03q5sasy2ihwnlz']
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:updateGroupPriorityOrdering"

Response

A successful response is empty.

{}

Handling Policies that Require Acknowledgement

Some policy schemas specify 'notices' for certain values of a particular field that require acknowledgement.

Example for policy chrome.users.PluginVmAllowd:

{
  "name": "customers/C0202nabg/policySchemas/chrome.users.PluginVmAllowed",
  "policyDescription": "Parallels Desktop.",
  # ...
  "fieldDescriptions": [
    {
      "field": "pluginVmAllowed",
      "description": "N/A",
      "knownValueDescriptions": [
        {
          "value": "true",
          "description": "Allow users to use Parallels Desktop."
        },
        {
          "value": "false",
          "description": "Do not allow users to use Parallels Desktop."
        }
      ]
    },
    {
      "field": "ackNoticeForPluginVmAllowedSetToTrue",
      "description": "This field must be set to true to acknowledge the notice message associated with the field 'plugin_vm_allowed' set to value 'true'. Please see the notices listed with this policy for more information."
    }
  ],
  "notices": [
    {
      "field": "pluginVmAllowed",
      "noticeValue": "true",
      "noticeMessage": "By enabling Parallels Desktop, you agree to the Parallels End-User License Agreement specified at https://www.parallels.com/about/legal/eula/. Warning: Device identifiers may be shared with Parallels. Please see privacy policy for more details at https://www.parallels.com/about/legal/privacy/. The minimum recommended configuration includes an i5 processor, 16 GB RAM, and 128 GB storage: https://support.google.com/chrome/a/answer/10044480.",
      "acknowledgementRequired": true
    }
  ],
  "supportUri": "...",
  "schemaName": "chrome.users.PluginVmAllowed"
}

In the above example, setting the field pluginVmAllowed's value to true is associated with a notice that has acknowledgementRequired. To properly set this field value to true, you will need to send a request that specifies the acknowledgement field ackNoticeForPluginVmAllowedSetToTrue to true, otherwise, you will get an error in your request.

In this example, you would need to send the following batch modify request.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
  'requests': [
    {
      'policyTargetKey': {
        'targetResource': 'orgunits/03ph8a2z10ybbh2'
      },
      'policyValue': {
        'policySchema': 'chrome.users.PluginVmAllowed',
        'value': {
          'pluginVmAllowed': true,
          'ackNoticeForPluginVmAllowedSetToTrue': true
        }
      },
      'updateMask': {
        'paths': [
          'pluginVmAllowed',
          'ackNoticeForPluginVmAllowedSetToTrue'
        ]
      }
    }
  ]
}" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"

Setting File Policies

Some policies have fields typed as UploadedFile, you'll need to upload the file you want to set as the value of those policies to the API server, in order to obtain an URL to use in BatchModify requests.

In this example we will be setting chrome.users.Wallpaper by uploading a JPEG file.

Upload the file

Request

curl -X POST \
  -H "Content-Type: image/jpeg" \
  -H "Authorization: Bearer $TOKEN" \
  -T "/path/to/the/file" \
  "https://chromepolicy.googleapis.com/upload/v1/customers/$CUSTOMER/policies/files:uploadPolicyFile?policy_field=chrome.users.Wallpaper.wallpaperImage"

Response

A successful response should contain the URL to access the file:

{
  "downloadUri": "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"
}

Set the file policy

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
        requests: [{
                policyTargetKey: {
                        targetResource: "orgunits/04fatzly4jbjho9",
                        },
                policyValue: {
                        policySchema: "chrome.users.Wallpaper",
                        value: {
                          wallpaperImage: {downloadUri: "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"}
                          }
                        },
                updateMask: {paths: "wallpaperImage"}
                }]
      }' \
  "https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"

Response

A successful response should be empty.

{}