The policy REST API manages privacyIDEA policies — the rule definitions that decide what an admin or user is allowed to do, what defaults apply, and how authentication and enrollment behave. See Policies for the conceptual chapter and Extended Policy Conditions for the policy-condition feature.

All endpoints require admin authentication. Reading is gated by the admin policy action policywrite, policyread, policydelete; create, update, enable, disable, rename and import by policywrite, policyread, policydelete; deletion by policywrite, policyread, policydelete. The introspection helpers under /policy/defs and /policy/check are admin-only.

16.1.1.13. Policy endpoints¶

The policy endpoints are a subset of the system endpoint.

You can read more about policies at Policies.

POST /policy/enable/(name)¶

Enable a policy. The policy definition is preserved; only the active flag is set to True.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

name – path component, the name of the policy.

Status Codes:

200 OK – database id of the policy in result.value.
404 Not Found – no policy with that name exists.

POST /policy/disable/(name)¶

Disable a policy. The policy definition is preserved; only the active flag is set to False.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

name – path component, the name of the policy.

Status Codes:

200 OK – database id of the policy in result.value.
404 Not Found – no policy with that name exists.

PATCH /policy/(old_name)¶

Rename a policy. Only the policy’s name is modified; all other attributes are preserved. The new name must satisfy the same character/prefix rules as a freshly-created policy (a-zA-Z0-9_.- plus space; check and the pi-update-policy- prefix are reserved).

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

old_name – path component, the current name of the policy.

JSON Parameters:

name – the new name to assign (required).

Status Codes:

200 OK – database id of the renamed policy in result.value.
400 Bad Request – old_name does not exist, name already exists, or name violates the character/prefix rules.

POST /policy/(name)¶

Create or update a policy. If a policy with the given name already exists, it is updated; otherwise it is created.

Policies in privacyIDEA gate what an admin or user is allowed to do, define defaults, and shape authentication and enrollment behavior. See Policies for the conceptual model and the available actions per scope, and Extended Policy Conditions for the optional condition mechanism.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

name – path component, the policy name. Allowed characters are a-zA-Z0-9_.-; whitespace is rejected. The literal check and any name starting with pi-update-policy- are reserved.

JSON Parameters:

scope – scope of the policy — one of admin, user, authentication, authorization, enrollment, webui, register, token, container (required).
action – scope-specific action or comma-separated list. Required for every scope except user (where it may be empty).
priority – integer priority; lower values bind first. Must be >= 1. Default 1.
description – free-form description.
adminrealm – admin realm the policy applies to (admin scope only). Validated against SUPERUSER_REALM from pi.cfg.
adminuser – comma-separated list of admin user names (admin scope only).
realm – user realm(s) for which the policy is valid. Validated against the configured realms.
resolver – resolver(s) for which the policy is valid. Validated against the configured resolvers.
user – user(s) the policy applies to — string with wildcards or list of strings.
time – time-of-day window during which the policy is active (see the policy reference for the format).
pinode – privacyIDEA node or list of nodes the policy applies to. Validated against the configured nodes.
client – client IP, optionally with a subnet (e.g. 172.16.0.0/16).
user_agents – list of user-agent identifiers the policy applies to.
active – boolean, whether the policy starts out active. Default True.
check_all_resolvers – if True, the policy is checked against every resolver in which the user exists.
conditions – list of policy conditions. Each entry is a 5- or 6-element list [section, key, comparator, value, active(, handle_missing_data)]. All conditions must match for the policy to take effect. The order of conditions is not guaranteed to be preserved.

Status Codes:

200 OK – {"setPolicy <name>": <db-id>} in result.value.
400 Bad Request – invalid scope, invalid policy name, priority below 1, invalid time format, or unknown realm / resolver / pinode / admin realm.

Example request:

POST /policy/pol1 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "scope": "admin",
  "realm": "realm1",
  "action": "enroll, disable",
  "conditions": [
    ["userinfo", "memberOf", "equals", "groupA", true]
  ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {"setPolicy pol1": 1}
  },
  "version": "privacyIDEA unknown"
}

GET /policy/export/(export)¶

GET /policy/(name)¶

GET /policy/¶

Return policy definitions, or export them to a file. The behavior depends on the URL shape:

/policy/ — return all policies (subject to the query filters) as a dictionary keyed by policy name.
/policy/<name> — return the named policy as a single-entry dictionary.
/policy/export/<filename> — export every policy to a .cfg file; the response Content-Type is text/plain and the filename in the path is suggested as the download name.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

name – path component, the name of a single policy.
export – path component, the suggested filename for the export download (e.g. policies.cfg).

Query Parameters:

realm – return only policies that apply to this realm.
scope – return only policies in the given scope.
active – true / false to filter by the active flag.

Status Codes:

200 OK – dictionary of policy definitions in result.value, or — for the export URL — a text/plain response body.

Example request:

GET /policy/pol1 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "pol_update_del": {
        "action": "enroll",
        "active": true,
        "client": "1.1.1.1",
        "name": "pol_update_del",
        "realm": "r1",
        "resolver": "test",
        "scope": "selfservice",
        "time": "",
        "user": "admin"
      }
    }
  },
  "version": "privacyIDEA unknown"
}

DELETE /policy/(name)¶

Delete the named policy.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

name – path component, the name of the policy to delete.

Status Codes:

200 OK – database id of the deleted policy in result.value.
404 Not Found – no policy with that name exists.

Example request:

DELETE /policy/pol1 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": 1
  },
  "version": "privacyIDEA unknown"
}

POST /policy/import/(filename)¶

Import policies from a previously-exported .cfg file. The request body must be multipart/form-data with a single field named file carrying the file contents. The path component filename is used only for logging — it does not have to match the uploaded file’s actual name.

Requires admin authentication and the policy action policywrite, policyread, policydelete.

Parameters:

filename – path component, used as a log/audit label for the imported file.

Request Headers:

Content-Type – multipart/form-data (required).

Form Parameters:

file – the file contents (required).

Status Codes:

200 OK – number of imported policies in result.value.
400 Bad Request – the file is empty or its contents are not valid text.

Example request:

POST /policy/import/backup-policy.cfg HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": 2
  },
  "version": "privacyIDEA unknown"
}

GET /policy/check¶

Probe whether a given (user, realm, scope, action, client, resolver) tuple would match any active policy. Used by the WebUI “Test policy” feature and as a self-check tool.

Requires admin authentication and the policy action policy_policyread.

Query Parameters:

user – user name (required).
realm – realm name (required).
scope – policy scope to check (required).
action – action to check (required).
client – client IP, optionally with a subnet.
resolver – resolver name.

Status Codes:

200 OK – result.value is {"allowed": true, "policy": <dict-of-matching-policies>} if at least one active policy matches, otherwise {"allowed": false, "info": "No policies found"}.

GET /policy/defs/(scope)¶

GET /policy/defs¶

Return the catalogue of possible policy definitions — the actions, types and metadata that the WebUI uses to render the policy editor. Two literal scope values produce introspection output instead of policy actions:

conditions — return {"sections": ..., "comparators": ..., "handle_missing_data": ...} describing the policy-condition vocabulary. Each map carries per-entry description and (for handle_missing_data) a WebUI-facing display_value.
pinodes — return the list of privacyIDEA node names declared in the server configuration.

Without scope, the response is a dictionary keyed by every known scope (admin, user, authentication, authorization, enrollment, webui, …) with the static + dynamically-discovered actions for each. With a regular scope name, only that scope’s entry is returned.

Requires admin authentication and the policy action policy_policyread.

Parameters:

scope – optional path component — a scope name (admin, user, …) or one of the literals conditions / pinodes.

Status Codes:

200 OK – dict (or list, for pinodes) of definitions in result.value.