Skip to main content

Group Policies API

See Groups and Group Policies for what a Group Policy is and how its settings apply to the accounts in the Groups it's assigned to. This page covers managing Group Policy objects themselves through the Management API — assigning one to a Group is done on the Group itself, via its userPolicies field.

Creating a Group Policy​

curl -X POST "https://{your-id-server}/api/rest/v1/group-policy" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "policyName": "Strong passwords",
    "enableMinPwLength": true,
    "minPwLength": 12
  }'

Requires access to the namespace and the USER_POLICY_CREATE permission.

A Group Policy has a large number of possible settings — password requirements, session timeouts, sign-in restrictions, locale defaults, and more — but each one is only active when its matching enableXxx boolean is also set to true. This is why the example above sets both minPwLength and enableMinPwLength: without the latter, the policy simply wouldn't apply minPwLength to anything. See your instance's /apidoc for the full list of settings and their enableXxx flags.

Reading, updating, and deleting a Group Policy​

curl "https://{your-id-server}/api/rest/v1/group-policy/{id}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

PUT replaces the whole policy — include every setting you want to keep, not just the ones you're changing. PATCH is also available for updating a subset of settings without resending the rest. Both require the USER_POLICY_MODIFY permission; deleting with DELETE requires USER_POLICY_REMOVE. A policy that's still assigned to one or more Groups can't be deleted until it's removed from all of them.

The namespace default policy is different​

A namespace's default policy looks like a Group Policy and uses the same settings, but it isn't one of the objects managed through this API — it's embedded directly on the namespace itself, as the defaultGroupPolicy field. Read or update it through the Namespace API instead.

Last updated on