Customization rules

Customization rules change the look, feel, and end-user experience of the Prisma Browser: the logo, theme color, home page, new-tab page, pinned shortcuts, admin messages, a EULA users must accept, force-installed web apps, and more. A customization rule has the same shape as a security rule: a controls map keyed by control name. Only the path (/policy/customization) and the available control names differ. See Policy overview for the shared concepts.

note

The Policy APIs are in Beta and are enabled by request. Contact your account team to join the Beta program.

Base path: /seb-api/v1/policy/customization.

Mandatory fields

Field	Required	Notes
`name`	Yes	1 to 300 characters
`mode`	Yes	`active` or `disabled`
`controls`	Yes	A map of control name to settings. Add at least one control to enforce policy.
`scope`	No (recommended)	Who the rule applies to. Omitting it applies the rule to everyone.
`description`	No	Up to 300 characters

Files come from the Assets API

Controls that use a file (logo, browser icon, background image, PAC file, EULA body, web app icon) do not take the binary directly. You first upload the file with the Assets API, which returns an asset ID, then set that ID on the control. For example, companyLogo.companyLogoId is the value returned by POST /assets/company-logo.

{
  "name": "Corporate branding",
  "mode": "active",
  "scope": { "users": { "isAny": true } },
  "controls": {
    "companyLogo": { "mode": "setCompanyLogo", "companyLogoId": "7c1e2f4a-3b5d-4e6f-8a9b-0c1d2e3f4a5b.png" },
    "themeColor": { "mode": "custom", "color": "#485BFF" }
  }
}

Create a customization rule

POST /seb-api/v1/policy/customization/rules

Show request and response

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Corporate branding",
        "mode": "active",
        "scope": { "users": { "isAny": true } },
        "controls": { "themeColor": { "mode": "custom", "color": "#485BFF" } }
      }'

Response:

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Delete a customization rule

curl -sS -X DELETE "$PB_API_BASE/policy/customization/rules/$RULE_ID" \
  -H "Authorization: Bearer $PB_TOKEN"

Returns 204 with an empty body.

Sections

Customization sections are created with POST /seb-api/v1/policy/customization/sections (only name is required) and ordered with the positions endpoints.

note

Every write edits the draft. Publish to make it live (see Draft and publish).

Examples

Expand an example to see the request, response, and notes.

Upload a logo and apply it (Assets API + companyLogo control)

The flagship two-API flow: upload the PNG to get a companyLogoId, then set it on the companyLogo control. See Assets for all asset types and their limits.

Step 1: upload the logo (multipart, like every asset upload)

curl -sS -X POST "$PB_API_BASE/assets/company-logo" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -F "file=@./company-logo.png"

Response (201 Created):

{ "companyLogoId": "7c1e2f4a-3b5d-4e6f-8a9b-0c1d2e3f4a5b.png" }

Step 2: set the returned ID on a customization rule

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Company logo",
        "mode": "active",
        "controls": {
          "companyLogo": { "mode": "setCompanyLogo", "companyLogoId": "7c1e2f4a-3b5d-4e6f-8a9b-0c1d2e3f4a5b.png" }
        }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Note: to remove the custom logo later, set companyLogo to { "mode": "noCompanyLogo" }. The company logo accepts only .png via the API. See Assets.

Set a fixed theme color

Force one theme color for everyone with mode: "custom" and a #RRGGBB hex value.

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Brand theme color",
        "mode": "active",
        "controls": { "themeColor": { "mode": "custom", "color": "#485BFF" } }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Pin managed shortcuts to the new-tab page

The managedShortcuts control sets the applications that appear on the new-tab page and in bookmarks. Use mode: "setShortcuts" and provide a shortcuts list of up to 200 entries, at most 16 of them with pinned: true. More than 16 pinned shortcuts returns 400.

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Company shortcuts",
        "mode": "active",
        "scope": { "users": { "isAny": true } },
        "controls": {
          "managedShortcuts": {
            "mode": "setShortcuts",
            "shortcuts": [
              { "name": "Workday", "url": "https://workday.example.com", "pinned": true },
              { "name": "Wiki", "url": "https://wiki.example.com", "pinned": true },
              { "name": "Support", "url": "https://support.example.com" }
            ]
          }
        }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Set the home page and new-tab page

Point the Home button at a fixed URL (homePage.mode: "customUrl") and open new tabs to a custom page (newTabPage.pageType: "customUrl").

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Company start pages",
        "mode": "active",
        "controls": {
          "homePage": {
            "mode": "customUrl",
            "customUrl": "https://intranet.example.com",
            "showHomePageButton": true
          },
          "newTabPage": {
            "pageType": "customUrl",
            "customUrl": "https://intranet.example.com/start"
          }
        }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Require users to accept a EULA

The eula control shows an End User License Agreement that users must accept. Upload the HTML body first with POST /assets/eula (a preview feature: send x-prisma-browser-preview: eula-upload), then set the returned eulaId as contentId. title (up to 100 characters) and contentId are required when enabled is true. See Assets for the upload.

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acceptable use agreement",
        "mode": "active",
        "scope": { "users": { "isAny": true } },
        "controls": {
          "eula": {
            "enabled": true,
            "title": "Acceptable use agreement",
            "contentId": "3f2b8c1e-7a4d-4e9b-9c21-5d6f0a1b2c3d.html"
          }
        }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Force-install web apps

The webAppForceList control silently installs up to 50 web apps (PWAs) that users cannot uninstall. Each url must be HTTPS and unique in the list. launchContainer is window (a standalone app window) or tab (the default). An icon is optional: omit webAppIcon to use the app's manifest icon, set webAppIcon.webAppIconId to an icon uploaded with POST /assets/web-app-icon, or set webAppIcon.iconUrl together with webAppIcon.iconHash (the SHA-256 of the file, 64 lowercase hex characters). Use one icon method per app. An empty webApps list installs nothing.

curl -sS -X POST "$PB_API_BASE/policy/customization/rules" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Company web apps",
        "mode": "active",
        "scope": { "users": { "isAny": true } },
        "controls": {
          "webAppForceList": {
            "webApps": [
              { "url": "https://timesheets.example.com", "displayName": "Timesheets", "launchContainer": "window", "createDesktopShortcut": true },
              { "url": "https://wiki.example.com" }
            ]
          }
        }
      }'

Response (201):

The resolved rule: the fields you sent, every server-side default filled in, and the new id.

Admin messages, network error tips, and IdP-synced shortcuts

adminMessages: up to 10 messages on the new-tab page. Set pushMessage: true on a message to open the admin messages dialog on the New Tab page.
networkErrorPopover (enable/disable): shows or hides the Troubleshooting Tips on network error pages.
identityProviderSyncedShortcuts: shows the applications assigned to the user in the identity provider as shortcuts on the New Tab page. With action: "enabled", set idpProvider to okta or entraID. For entraID, also set idpAppsProviderId to an enabled Entra ID application sync provider (list them with GET /integrations/idp-application-sync). With action: "disabled", omit both fields.

curl -sS -X PATCH "$PB_API_BASE/policy/customization/rules/$RULE_ID" \
  -H "Authorization: Bearer $PB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "controls": {
          "adminMessages": {
            "mode": "enabled",
            "messages": [
              { "title": "Maintenance on Saturday", "description": "Email will be unavailable from 02:00 to 04:00 UTC.", "pushMessage": true }
            ]
          },
          "networkErrorPopover": { "action": "disable" },
          "identityProviderSyncedShortcuts": { "action": "enabled", "idpProvider": "okta" }
        }
      }'

Response (200):

{ "id": "0RLEXAMP1ECVST0M1ZAT10NXXXXXX" }

Policy overview, Security rules
Building blocks: Assets

Customization rules

Mandatory fields​

Files come from the Assets API​

Create a customization rule​

Delete a customization rule​

Sections​

Examples​

Related​

Mandatory fields

Files come from the Assets API

Create a customization rule

Delete a customization rule

Sections

Examples

Related