Skip to main content
V
VishalSanap08
Level 1.5: Cupcake
December 2, 2025
Solved

Not able to set wallpaper on managed chromebook using the Policy API from GWS

  • December 2, 2025
  • 4 replies
  • 2 views

Hello Team,

While testing the wallpaper management functionality using the Chrome Policy API, we observed that the wallpaper does not get applied on managed ChromeOS devices, even though the API calls return a successful response.

When we upload the wallpaper image using the uploadPolicyFile endpoint, it successfully returns a valid downloadUri.and wallpaper gets applied on device. However, when we attempt to apply this uploaded image as a wallpaper using the Policy API, the request completes successfully (200 OK), but the wallpaper does not apply on the chromebook device.

We’d appreciate your help confirming the following points:

Are there any additional parameters, permissions, or policy fields required for either of the following?

chrome.users.Wallpaper
chrome.devices.managedguest.Wallpaper

Are there any known propagation delays, caching behaviors, or policy refresh constraints that could affect wallpaper deployment on managed devices?

Best answer by Lynda

Hi @VishalSanap08 welcome to the community and thanks for your question.

 

Can I check you are using the specific JSON structure required in the Policy API request, not just the URI?

 

The value you send for the policy must be a JSON object containing:

  • url: The downloadUri from the uploadPolicyFile endpoint.
  • hash: The SHA-1 hash of the uploaded image file. This is critical for integrity check.
  • placement: Set to CENTER_CROP.
  • source: Set to POLICY.

 

Example JSON Value (Policy API Payload): {"url": "...", "hash": "...", "placement": "CENTER_CROP", "source": "POLICY"}

 

Also I include some initial troubleshooting steps to consider:

 

  1. Verify JSON Structure: Double-check that your Policy API call includes the SHA-1 hash and all required fields (url, hash, placement, source) in the value payload.
  2. Force Refresh: On a test Chromebook, go to chrome://policy and click Reload policies. Check if the new wallpaper policy value (including the url and hash) appears correctly on this page. If it is correct, wait a few minutes for the device to download the file.
  3. Check Permissions: Ensure your service account/user has the correct Admin SDK Directory API permissions to manage User or Device policies, as applicable.

Let's also see if any other IT Admins across the community have advice on this topic.

4 replies

Lynda
LyndaAnswer
Community Manager
December 2, 2025

Hi @VishalSanap08 welcome to the community and thanks for your question.

 

Can I check you are using the specific JSON structure required in the Policy API request, not just the URI?

 

The value you send for the policy must be a JSON object containing:

  • url: The downloadUri from the uploadPolicyFile endpoint.
  • hash: The SHA-1 hash of the uploaded image file. This is critical for integrity check.
  • placement: Set to CENTER_CROP.
  • source: Set to POLICY.

 

Example JSON Value (Policy API Payload): {"url": "...", "hash": "...", "placement": "CENTER_CROP", "source": "POLICY"}

 

Also I include some initial troubleshooting steps to consider:

 

  1. Verify JSON Structure: Double-check that your Policy API call includes the SHA-1 hash and all required fields (url, hash, placement, source) in the value payload.
  2. Force Refresh: On a test Chromebook, go to chrome://policy and click Reload policies. Check if the new wallpaper policy value (including the url and hash) appears correctly on this page. If it is correct, wait a few minutes for the device to download the file.
  3. Check Permissions: Ensure your service account/user has the correct Admin SDK Directory API permissions to manage User or Device policies, as applicable.

Let's also see if any other IT Admins across the community have advice on this topic.

    V
    VishalSanap08Author
    Level 1.5: Cupcake
    December 5, 2025

    Thanks Lynda. This was helpful. I was able to set wallpaper successfully 

      V
      VishalSanap08Author
      Level 1.5: Cupcake
      January 16, 2026

      Hello @Lynda ,

      I have a new query. We are able to set the wallpaper via API; however, in GWS there is a Delete option that removes the applied wallpaper and restores the system default.

      Do we have any API available to perform this action programmatically, instead of using the UI button?

      Lynda
      Lynda
      Community Manager
      January 19, 2026

      Hi @VishalSanap08 

       

      Glad to hear the JSON structure resolved the initial issue! Can you try the following to see if it works like you'd hoped? To programmatically "delete" the wallpaper and restore the system default, you don't use a "delete" endpoint; instead, you use the batchModify method to remove the policy override from the specific Organizational Unit (OU).

       

      Key Advice:

      • Endpoint: Use POST https://chromepolicy.googleapis.com/v1/customers/{customer}/policies/orgunits:batchModify
      • The Logic: To "delete" the UI setting via API, you send a request for the chrome.users.Wallpaper (or managed guest) schema but omit the value field in your policyValue object. This tells the API to remove the local override and revert to the parent’s setting or the system default.
      • Update Mask: Ensure your request includes an updateMask set to "value".

      Example JSON Payload:

      JSON

      { "requests": [ { "policyTargetKey": { "targetResource": "orgunits/YOUR_OU_ID" }, "policyValue": { "policySchema": "chrome.users.Wallpaper" }, "updateMask": "value" } ] }

      Verification: After running the API call, have the user go to chrome://policy and click Reload policies. The wallpaper policy should either disappear or show as "Not Set," which triggers the device to revert to the default system wallpaper.

       

      If it doesn't behave as intended, let us know. Thanks!

      V
      VishalSanap08Author
      Level 1.5: Cupcake
      January 28, 2026

      We tested the proposed updateMask value approach using the customers.policies.orgunits.batchModify API. The API strictly requires policyValue.value for org unit level policies and rejects requests when this field is missing. As a result, the chrome.users.Wallpaper policy cannot be unset via the public API at the org unit level, even though the Admin Console allows resetting the policy to its default value.

      Terms & ConditionsCookie settingsAccessibility statement