Replace a policy branch

Request

Early AccessIdentity Engine

OAuth 2.0 scope:

okta.policies.manage

Replaces the name, description, or comments of a policy branch.

You can update the monitoring time period of STAGED branches with this endpoint.

Only applicable to ACCESS_POLICY type policies.

Path

policyIdstringrequired

id of the ACCESS_POLICY

Example:rst1d7xus97faIAgmti0

branchIdstringrequired

id of the policy branch

Example:rsb1d7xus97faIAgmti

Bodyapplication/jsonrequired

branchInformationobject(PolicyBranchRequestBranchInformation)

Branch information supplied when replacing a policy branch

descriptionstring, <= 1024 characters

Description of the policy branch

Example:"Testing stricter authentication requirements for Q2"

namestring, <= 255 charactersrequired

Name of the policy branch

Example:"Q2 Security Updates"

PUT

/api/v1/policies/{policyId}/branches/{branchId}

curl -i -X PUT \
  https://subdomain.okta.com/api/v1/policies/rst1d7xus97faIAgmti0/branches/rsb1d7xus97faIAgmti \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Q2 Security Updates - Final",
    "description": "Ready for production deployment after successful testing",
    "branchInformation": {
      "id": "rsb2k8pqr14hbJCnzuj",
      "status": "STAGED",
      "comments": "Approved by security team for staging",
      "settings": {
        "monitoring": {
          "expiry": "2026-08-15T00:00:00.000Z"
        }
      }
    }
  }'

Responses

Success

Bodyapplication/json

branchInformationobject(PolicyBranchInformation)

Information about the branch of the policy object, including its status

conditionsstring or null

Policy conditions aren't supported for ACCESS_POLICY. Conditions are applied at the rule level.

Default:null

createdstring, (date-time)read-only

Timestamp when the policy branch was created

descriptionstring

Description of the policy

idstringread-only

Identifier of the policy

lastUpdatedstring, (date-time)read-only

Timestamp when the policy branch was last modified

namestringrequired

Name of the policy

priorityinteger

Specifies the order in which this policy is evaluated in relation to the other policies

statusstring(LifecycleStatus)

Whether or not the policy is active. Use the activate query parameter to set the status of a policy.

Enum:"ACTIVE""INACTIVE"

systemboolean

Specifies whether Okta created the policy

Default:false

typestringrequired

Policy type. Branching is only supported for ACCESS_POLICY policies.

Value:"ACCESS_POLICY"

_embeddedobjectread-only

_linksobject(PolicyBranchLinks)read-only

Response

{
  "id": "rst2k8pqr14hbJCnzuj0",
  "status": "ACTIVE",
  "name": "Q2 Security Updates - Final",
  "description": "Ready for production deployment after successful testing",
  "priority": 1,
  "system": false,
  "type": "ACCESS_POLICY",
  "conditions": null,
  "created": "2026-04-01T10:15:30.000Z",
  "lastUpdated": "2026-05-06T13:45:00.000Z",
  "branchInformation": {
    "id": "rsb2k8pqr14hbJCnzuj",
    "status": "STAGED",
    "comments": "Approved by security team for staging",
    "settings": { … }
  },
  "_links": {
    "self": { … },
    "rules": { … },
    "promote": { … }
  }
}