Skip to content
Okta Admin Management API
/
Access Controls
/
/
Promote a policy branch

Promote a policy branch

Request

Early AccessIdentity Engine
OAuth 2.0 scope:
  • okta.policies.manage

Promotes a DRAFT or STAGED branch to LIVE status, replacing the existing live branch. You can only have one LIVE branch for a policy at a time.

If the current LIVE branch has been modified since this branch was created, the request returns a 409 conflict error. Use the ignoreConflict=true query parameter to promote anyway and overwrite those changes.

Only applicable to ACCESS_POLICY type policies.

Path
policyIdstringrequired

id of the ACCESS_POLICY

Example:rst1d7xus97faIAgmti0
branchIdstringrequired

id of the policy branch

Example:rsb1d7xus97faIAgmti
Query
ignoreConflictboolean

If you set it as true, the specified branch is promoted, even if the current LIVE branch has been modified since the promotion branch was created. Any differences between the two branches are overwritten by the branch that's promoted.

Default:false
Bodyapplication/json
commentsstring, <= 1024 characters

Comments or notes about the lifecycle operation that the branch is affected by

Example:"Promoting to production after successful testing"
POST
/api/v1/policies/{policyId}/branches/{branchId}/lifecycle/promote
curl -i -X POST \
  'https://subdomain.okta.com/api/v1/policies/rst1d7xus97faIAgmti0/branches/rsb1d7xus97faIAgmti/lifecycle/promote?ignoreConflict=false' \
  -H 'Content-Type: application/json' \
  -d '{
    "comments": "Promoting Q2 security updates to production after successful staging"
  }'

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
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-06T14:00:00.000Z",
  "branchInformation": {
    "id": "rsb2k8pqr14hbJCnzuj",
    "status": "LIVE",
    "comments": "Promoting Q2 security updates to production after successful staging"
  },
  "_links": {
    "self": { … },
    "rules": { … }
  }
}