Policy

Policy is how the Prisma Browser decides what users can do: who a rule applies to (scope) and what happens (an action or a set of controls). Policy is organized into separate policy types, each an ordered list of rules grouped into sections and evaluated top to bottom.

This page covers what is common to all policy types. For the fields, structure, and mandatory inputs specific to each type, see its page.

note

The Policy APIs are in Beta and are enabled by request. This applies to all four policy types. Contact your account team to join the Beta program.

The policy types

Policy type	Page	What it governs
Sign-in	Sign-in rules	Whether and how users can sign in to the Prisma Browser
Access and data	Access and data rules	Which applications and URLs are reachable, and how data moves (login and data controls, DLP)
Security	Security rules	Browser hardening controls (extensions, cookies, certificates, sessions, HTTPS)
Customization	Customization rules	Branding and look-and-feel controls (logo, theme, shortcuts, start pages)

Each policy type has the same shape of endpoints (substitute the type):

GET    /seb-api/v1/policy/{type}                 list rules + sections (paginated, filterable)
POST   /seb-api/v1/policy/{type}/rules           create a rule
GET    /seb-api/v1/policy/{type}/rules/{id}      get one rule (full detail)
PATCH  /seb-api/v1/policy/{type}/rules/{id}      update a rule
DELETE /seb-api/v1/policy/{type}/rules/{id}      delete a rule

note

No "list rules" endpoint. You list a policy's rules by reading the whole policy (GET /policy/{type}), which returns rules and sections interleaved in evaluation order. List items are summaries; fetch a rule's full body with GET /policy/{type}/rules/{id}.

A tenant can have up to 1,000 rules per policy type. Built-in and default rules are not counted. Creating a rule that would take a policy type above 1,000 returns 400; publish also returns 400 if the draft would grow past it. 1,000 is the default and can be raised per tenant; contact your account team.

Find rules

GET /policy/{type} takes query filters, so you can find the rules that apply to a user or carry a control without reading the whole policy. Repeat a parameter to pass several values.

Filter	Matches
name	Rule name contains the value, case-insensitive
id, mode	Rule ID, rule mode
user, userGroup	User or user group ID. Includes any-scope rules and rules scoped to a group that contains the user, unless you add userExplicitOnly=true
userName, userEmail	User name or email contains the value, case-insensitive (at least 3 characters). Combines with user
deviceGroup	Device group ID. Includes default rules unless you add deviceGroupExplicitOnly=true
control	Security and Customization: rules that carry this control key
dataControl, loginControl	Access and data: rules that carry this data or login control key. Access and data rules also filter by application, DLP profile, web classification, and log level
action	Sign-in: rule action

curl -sS -G "$PB_API_BASE/policy/security" \
  -H "Authorization: Bearer $PB_TOKEN" \
  --data-urlencode "control=sessionRefresh"

Scope: who a rule applies to

scope selects users, user groups, device groups, IPs, and locations. Every segment supports isAny (apply to all) plus add/remove deltas so you can change membership without read-modify-write:

{
  "scope": {
    "users": {
      "addUsers": ["0UREXAMPLEUSERXXXXXXXXXXXXX"],
      "removeUsers": ["0UREXAMPLEOLDUSERXXXXXXXXXX"],
      "addUserGroups": ["0UGEXAMPLEGROUPXXXXXXXXXXXX"]
    }
  }
}

Scope segment	Add / remove fields
Users and user groups	addUsers / removeUsers, addUserGroups / removeUserGroups
Device groups	addDeviceGroups / removeDeviceGroups
Public / private IPs	addPublicIps / removePublicIps, addPrivateIps / removePrivateIps
Locations	addLocations / removeLocations

scope is optional on create for every policy type, but leaving it off means the rule applies to everyone. Always set a scope unless you intend a tenant-wide rule. See Change a rule's scope.

Sections and positions

Rules are organized into sections and evaluated in order. Sections are identical across all policy types: create one with POST /policy/{type}/sections (only name is required), and manage one with GET / PUT / PATCH / DELETE /policy/{type}/sections/{id}.

Ordering is managed through the positions sub-resource of each type:

• PUT /policy/{type}/positions submits the full ordered list of rules and sections. Index 0 is evaluated first; rules in a section must be contiguous.
• PATCH /policy/{type}/positions applies partial moves (top / bottom / before / after an anchor, with a target section), applied atomically, without resubmitting the whole order. Up to 100 moves per request; see Bulk operations in Entity limits.

See Reorder rules and sections for both approaches.

Action vs controls

What a rule "does" depends on its type:

Policy type	What it carries
Sign-in	A single action: allow, block, or prompt
Access and data	An action plus application scope, login controls, and data controls
Security, Customization	A controls map (many named controls, each with its own settings)

note

Controls are replaced whole, not delta-patched. In a PATCH, omitted controls are preserved and a control you include fully replaces its previous body. Sending null removes a control (at least one must remain). There is no per-element delta inside a control. To add one item to a control's list (for example, an allowed extension), read the control, append, and PATCH the whole control back. See Manage allowed browser extensions.

Prompts and custom messages

When an action or control prompts the user, a userPrompt object chooses how:

mode	What the user sees
none	No prompt
warnAndAllow	A warning they can dismiss to continue
proceedWithReason	They must type a justification to continue
adminApproval	They submit a request an administrator must approve

The custom message text shown to the user (typically on a block) is a separate customDialogText object with title (1-80 chars, required), description, and an optional externalLink ({ label, url }). The description limit depends on where the dialog appears: up to 5000 characters on access dialogs (block, redirect, and Open in Prisma Browser pages), up to 500 on data control dialogs (clipboard, file download, file upload), and up to 360 everywhere else. See each type's page for which actions and controls support prompts and custom text.

Patch semantics summary

Field kind	PATCH behavior
Scalars (name, mode)	Set to the new value
Scope lists	Delta via add… / remove…, or full replace
Application scope (access and data)	Delta via addApplicationIds / addUrls / etc., or full replace
Controls (security, customization)	Whole-control replace; null removes; omitted preserved

See Delta patch for the full model. Every write here targets the draft; publish to make it live (see Draft and publish).

Related

• Policy types: Sign-in rules, Access and data rules, Security rules, Customization rules
• Use cases: Create and publish a rule, Change a rule's scope, Reorder rules and sections