---
title: "Apply desktop-policies by stable key"
method: PUT
path: "/v1/desktop-policies/by-key/{externalKey}"
tags: ["Desktop Policies"]
---

# Apply desktop-policies by stable key

`PUT /v1/desktop-policies/by-key/{externalKey}`

Creates or replaces an organization-scoped resource. Names do not identify resources; existing unkeyed resources are never adopted automatically. Assignments are replaced. Omitted write-only secrets are preserved. Concurrent writes are last-write-wins; conditional headers are not supported on this route.

## Path parameters

- `externalKey` string, required

## Request body

- object
  - `policyName` string, required
  - `policy` DenDesktopPolicyDocumentWrite, required
    - `allowCustomProviders` boolean
    - `allowZenModel` boolean
    - `allowMultipleWorkspaces` boolean
    - `allowControlSettings` boolean
    - `allowManageExtensions` boolean
    - `allowBuiltInExtensions` boolean
    - `allowAlphaUpdates` boolean
    - `showWelcomePage` boolean
    - `access` object
      - `mode` 'custom' | 'locked', required
      - `capabilities` DenDesktopPolicyValue, required
        - `allowCustomProviders` boolean
        - `allowZenModel` boolean
        - `allowMultipleWorkspaces` boolean
        - `allowControlSettings` boolean
        - `allowManageExtensions` boolean
        - `allowBuiltInExtensions` boolean
        - `allowAlphaUpdates` boolean
        - `showWelcomePage` boolean
    - `execution` object
      - `commands` 'allow' | 'deny'
      - `blockedCommands` string[]
      - `browserOrigins` string[]
      - `blockBrowserUploads` boolean
    - `onboardingPrompts` string[], nullable
    - `onboardingPromptDescriptions` string[], nullable
  - `priority` integer
  - `isEnabled` boolean
  - `memberIds` string[]
  - `teamIds` string[]
  - `roles` string[]

## Response `200`

The existing resource was replaced.

- DesktopPolicyResponse
  - `desktopPolicy` object, required

## Other responses

- `201` — The resource was created.
- `400` — Invalid declarative request.
- `401` — Authentication required.
- `403` — Resource management permission required.
- `404` — A referenced resource was not found.
- `409` — A name or identity conflict requires reconciliation.

## Changes

- **2026-09-11** `bb8ff73e4ad3` — 2 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - the endpoint scheme security `denApiKey` was added to the API
- **2026-09-07** `ffcccb610e8a` — 1 info
  - added the new optional request property `policy/execution`
- **2026-09-05** `cb34559d4b4d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/desktop-policies/by-key/:externalKey/put.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/6117f1cac9d7?raw)