Code samples for the Chrome Policy API

Please refer to Chrome Policy API page for a high level overview of api features.

Below requests illustrate policy management via Policy API on example of printer policies. 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 \
  --header "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 word "printer" in the name and word "devices" in description you may apply fllowing value to the filter name=printers AND description=devices. Learn more about filter syntax.

Request:

  curl -X GET \
  --header "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 example for chrome.printers.AllowForUsers schema.

Request:

  curl -X GET \
  --header "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 identifier of a printer.

Read policy value in Organizational Unit

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

In the response, notice sourceKey field, which specifies which Organizational Unit the value of the policy comes from.

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

Request:

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

Response:

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

Read multiple policies in Organizational Unit

Providing a schema namespace with * (example chrome.printers.*) allows to read values for all policies under this namespace in a particular Organizational Unit. Read about schema namespaces on Policy Schemas page.

Request:

  curl -X POST \
  -H "Content-Type: application/json" \
  --header "Authorization: Bearer $TOKEN" \
  -d '{
        policyTargetKey: {
          targetResource: "orgunits/04fatzly4jbjho9",
        },
        policySchemaFilter: "chrome.printers.*"
    }' \
  "https://chromepolicy.googleapis.com/v1/customers/C0202nabg/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 in Organizational Unit

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.

In modify requests, we need to specify an updateMask. Update mask lists all 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.

To disallow a printer 0gjdgxs208tpef for users in the Organizational Unit 04fatzly4jbjho9 we need to send the following request:

Request:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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/C0202nabg/policies/orgunits:batchModify"

Response:

A successful response is empty. {}

Modify multiple policies at once

BatchModify method, allows to send multiple policy modifications at the same time. However, not all policies can be batched together. For the rules on batching see Policy API page.

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 and the same Organizational Unit.

Request:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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 policy value in Organizational Unit

BatchInherit method allows to modify status of policy in 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. BatchInherit method, allows to send multiple policy inherit request at the same time. However, not all policies can be batched together. For the rules on batching see Policy API page.

Request:

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

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 sse 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. In order 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" \
  --header "Authorization: Bearer $TOKEN" \
  -d "{
  'requests': [
    {
      'policyTargetKey': {
        'targetResource': 'orgunits/03ph8a2z10ybbh2'
      },
      'policyValue': {
        'policySchema': 'chrome.users.PluginVmAllowed',
        'value': {
          'pluginVmAllowed': true,
          'ackNoticeForPluginVmAllowedSetToTrue': true
        }
      },
      'updateMask': {
        'paths': [
          'pluginVmAllowed',
          'ackNoticeForPluginVmAllowedSetToTrue'
        ]
      }
    }
  ]
}"

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 an jpeg file.

Upload the file

Request:

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

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" \
  --header "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/C0202nabg/policies/orgunits:batchModify"

A successful response should be empty:

{}