Skip to content
Okta Admin Management API
/
/Policy Branching

Policy Branching

The Policy Branching API enables you to manage, test, and monitor branches of your app sign-in policies before enabling your new configuration and enforcing it for your end users and apps. This feature is only available for app sign-in (ACCESS_POLICY type) policies.

Note: This functionality is available as a self-service Early Access (EA) feature for Identity Engine orgs. To use it, enable the Change management for app sign-in policies feature. See Self-service features.

Conceptually, policy branches work in a similar way as Git branches. However, you can only manage branches for app sign-in policies, and only operations under this API are supported for managing them. For more information about how policy branching works, see Manage staged app sign-in policy branches.

These are the different statuses that a policy branch can have:

  • DRAFT: A new branch that's created from the live policy. Rules are inherited from the live branch and can be edited. Only one DRAFT or STAGED branch can exist per policy at a time.
  • STAGED: A branch that has been staged can be edited and monitored. Rules can be added, updated, or deleted. And you can enable monitoring to observe how the rules behave before promoting the branch to LIVE. Only one STAGED or DRAFT branch can exist per policy at a time.
  • LIVE: The set of policy rules that are currently enforced. This is the standard branch state for an app sign-in policy.

A policy can have a maximum of two branches across all statuses. When you create a new draft branch, the existing draft branch is deleted. See the following example of the number of branches a policy can have:

  • Policy A
    • Branch 1 (LIVE)
    • Branch 2 (DRAFT or STAGED)

Branch workflow

The following steps outline a typical workflow for managing policy branches:

  1. Create a branch of an existing live policy to make changes without affecting the active configuration. Use the Create a policy branch endpoint.
  2. Stage the branch. Staging changes the status from DRAFT to STAGED allows you to enable monitoring of the branch. You can also edit and update the rules of the policy branch as needed. Use the Stage a policy branch endpoint.
  3. Add, update, or delete policy branch rules as needed. Rules can be modified on STAGED or DRAFT branches. Use the Create a policy branch rule endpoint or Replace a policy branch rule endpoint.
  4. If you're satisfied with the changes, promote the STAGED branch to LIVE, making it the active and enforced policy. Use the Promote a policy branch endpoint.
  5. Optional. If you want to restore the previous live branch, review archived policy branches by using the List the policy's branch history endpoint. You can then use the Restore a policy branch endpoint to restore an archived branch.
Languages
Servers
https://{yourOktaDomain}