Update Policy Configuration

Update policy version configuration including conditions, actions, and settings

Endpoints

PUT /api/private/lifecycle_management/policies/{policy_id}/versions/{version_number}

PATCH /api/private/lifecycle_management/policies/{policy_id}/versions/{version_number}

Description

Update a specific version of an existing policy, including workflows, conditions, actions, and configuration settings. This endpoint allows you to modify the policy version's behavior and structure.

Use this endpoint to:

• Modify policy version workflows, conditions, and actions

• Update attribute transformers and lookup table references

• Adjust password complexity rules and mover properties

• Configure transformer functions for the policy version

Configuration changes to active policies take effect immediately. Consider testing changes in a draft policy first, or temporarily setting the policy to inactive during updates.

Version Number Usage: You must update the specific version that is currently active or the version you want to modify. Use Get Policy to retrieve the current_version_number before making updates. You cannot create new versions through this endpoint; it only updates existing versions.

Authentication Required

This endpoint requires a valid Veza API key for authentication.

See Authentication for more about creating and managing API keys.

All requests must include the API key as a Bearer token in the Authorization header.

Example:

curl -X GET "$BASE_URL/api/preview/keys" \
  -H "authorization: Bearer $VEZA_TOKEN"

API Reference

patch

Authorizations

Path parameters

value.policy_idstringRequired

value.version_numberstringRequired

Query parameters

update_maskstring · field-maskOptional

Body

A version of a policy, this includes the watcher profile for what starts the policy

policy_idstringOptional

version_numberinteger · int32Read-onlyOptional

stateinteger · enumOptional

config_versionstringRead-onlyOptional

This is the version of the config in case it changes in the future

created_bystringRead-onlyOptional

created_atstring · date-timeRead-onlyOptional

updated_atstring · date-timeRead-onlyOptional

published_bystringRead-onlyOptional

published_atstring · date-timeRead-onlyOptional

Responses

200

OK

application/json

default

Default error response

application/json

patch

HTTPcURLJavaScriptPython

PATCH /api/private/lifecycle_management/policies/{value.policy_id}/versions/{value.version_number} HTTP/1.1
Host: your-tenant.cookiecloud.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 2130

{
  "policy_id": "text",
  "state": 1,
  "config": {
    "workflows": [
      {
        "trigger_type": 1,
        "description": "text",
        "trigger_string": "text",
        "conditions_on_success": [
          {
            "condition_type": 1,
            "condition_string": "text",
            "actions_to_run": [
              {
                "name": "text",
                "type": 1
              }
            ],
            "name": "text",
            "continue_actions_if_any_error": true,
            "state": 1
          }
        ],
        "continuous_sync": true,
        "name": "text",
        "state": 1,
        "attribute_to_get_execute_date": "text",
        "local_time_zone_diff_from_utc": 1,
        "local_time_zone_attribute": "text",
        "trigger_at_local_time_hour": 1,
        "execute_date_time_formatters": [
          {
            "date_formatter": "text",
            "pipeline_functions": "text"
          }
        ],
        "grace_period_in_sec": 1,
        "skip_trigger_recheck_after_grace_period": true,
        "priority": 1
      }
    ],
    "actions": [
      {
        "name": "text",
        "description": "text",
        "type": 1,
        "config": {
          "@type": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "conditions_on_success": [
          {
            "condition_type": 1,
            "condition_string": "text",
            "actions_to_run": [
              {
                "name": "text",
                "type": 1
              }
            ],
            "name": "text",
            "continue_actions_if_any_error": true,
            "state": 1
          }
        ],
        "action_notification_settings": [
          {
            "notification_settings": {
              "notification_type": 1,
              "notification_id": "text",
              "type_settings": {
                "@type": "text",
                "ANY_ADDITIONAL_PROPERTY": "anything"
              }
            },
            "on_success": true,
            "on_failure": true
          }
        ],
        "state": 1,
        "run_once": true
      }
    ],
    "attribute_common_transformers": [
      {
        "name": "text",
        "description": "text",
        "entity_type": "text",
        "entity_attribute_transformers": [
          {
            "destination_attribute": "text",
            "destination_value_formatter": "text",
            "continuous_sync": true,
            "additional_value_formatter": [
              "text"
            ],
            "pipeline_functions": "text",
            "unique_identifier": true
          }
        ]
      }
    ],
    "lookup_table_references": [
      {
        "name": "text",
        "description": "text",
        "column_names": [
          "text"
        ],
        "lookup_table_id": "text"
      }
    ],
    "mover_properties": [
      "text"
    ],
    "password_complexity_rules": [
      {
        "name": "text",
        "length": 1,
        "use_special_characters": true,
        "use_numbers": true,
        "use_uppercase": true,
        "use_lowercase": true,
        "disallowed_characters": "text"
      }
    ],
    "transformer_functions": [
      {
        "function_expression": "text",
        "definition": {
          "name": "text",
          "description": "text",
          "parameters": [
            {
              "name": "text",
              "description": "text",
              "type": 1,
              "allow_empty": true,
              "optional": true,
              "valid_values": [
                "text"
              ]
            }
          ],
          "require_no_input": true,
          "return_multiple_values": true,
          "input_is_optional": true
        }
      }
    ]
  }
}

{
  "value": {
    "policy_id": "text",
    "version_number": 1,
    "state": 1,
    "config": {
      "workflows": [
        {
          "trigger_type": 1,
          "description": "text",
          "trigger_string": "text",
          "conditions_on_success": [
            {
              "condition_type": 1,
              "condition_string": "text",
              "actions_to_run": [
                {
                  "name": "text",
                  "type": 1
                }
              ],
              "name": "text",
              "continue_actions_if_any_error": true,
              "state": 1
            }
          ],
          "continuous_sync": true,
          "name": "text",
          "state": 1,
          "attribute_to_get_execute_date": "text",
          "local_time_zone_diff_from_utc": 1,
          "local_time_zone_attribute": "text",
          "trigger_at_local_time_hour": 1,
          "execute_date_time_formatters": [
            {
              "date_formatter": "text",
              "pipeline_functions": "text"
            }
          ],
          "grace_period_in_sec": 1,
          "skip_trigger_recheck_after_grace_period": true,
          "priority": 1
        }
      ],
      "actions": [
        {
          "name": "text",
          "description": "text",
          "type": 1,
          "config": {
            "@type": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "conditions_on_success": [
            {
              "condition_type": 1,
              "condition_string": "text",
              "actions_to_run": [
                {
                  "name": "text",
                  "type": 1
                }
              ],
              "name": "text",
              "continue_actions_if_any_error": true,
              "state": 1
            }
          ],
          "action_notification_settings": [
            {
              "notification_settings": {
                "notification_type": 1,
                "notification_id": "text",
                "type_settings": {
                  "@type": "text",
                  "ANY_ADDITIONAL_PROPERTY": "anything"
                }
              },
              "on_success": true,
              "on_failure": true
            }
          ],
          "state": 1,
          "run_once": true
        }
      ],
      "attribute_common_transformers": [
        {
          "name": "text",
          "description": "text",
          "entity_type": "text",
          "entity_attribute_transformers": [
            {
              "destination_attribute": "text",
              "destination_value_formatter": "text",
              "continuous_sync": true,
              "additional_value_formatter": [
                "text"
              ],
              "pipeline_functions": "text",
              "unique_identifier": true
            }
          ]
        }
      ],
      "lookup_table_references": [
        {
          "name": "text",
          "description": "text",
          "column_names": [
            "text"
          ],
          "lookup_table_id": "text"
        }
      ],
      "mover_properties": [
        "text"
      ],
      "password_complexity_rules": [
        {
          "name": "text",
          "length": 1,
          "use_special_characters": true,
          "use_numbers": true,
          "use_uppercase": true,
          "use_lowercase": true,
          "disallowed_characters": "text"
        }
      ],
      "transformer_functions": [
        {
          "function_expression": "text",
          "definition": {
            "name": "text",
            "description": "text",
            "parameters": [
              {
                "name": "text",
                "description": "text",
                "type": 1,
                "allow_empty": true,
                "optional": true,
                "valid_values": [
                  "text"
                ]
              }
            ],
            "require_no_input": true,
            "return_multiple_values": true,
            "input_is_optional": true
          }
        }
      ]
    },
    "config_version": "text",
    "created_by": "text",
    "created_at": "2025-08-25T14:57:06.977Z",
    "updated_at": "2025-08-25T14:57:06.977Z",
    "published_by": "text",
    "published_at": "2025-08-25T14:57:06.977Z"
  }
}

Request Examples

Path Parameters

Parameter	Type	Required	Description
policy_id	string	Yes	Unique identifier of the policy
version_number	integer	Yes	Version number of the policy version to update

Request Body

Field	Type	Required	Description
value	object	Yes	The updated PolicyVersion object
update_mask	object	No	Field mask specifying which fields to update

PolicyVersion Object Fields

Field	Type	Required	Description
policy_id	string	Yes	ID of the policy this version belongs to
version_number	integer	No	Version number (output only)
state	string	No	Version state: DRAFT, PUBLISHED, RETIRED
config	object	No	Policy version configuration containing workflows, actions, and transformers

Configuration Object Details

The config field contains the core policy version logic:

Field	Type	Description
workflows	array[object]	Array of workflow objects that define when and how the policy triggers
actions	array[object]	Array of action objects that define what happens when conditions are met
attribute_common_transformers	array[object]	Common attribute transformation rules
lookup_table_references	array[object]	References to lookup tables used by the policy
mover_properties	array[string]	List of properties that, when changed, mark an identity as a "mover"
password_complexity_rules	array[object]	Password complexity rules for sync operations
transformer_functions	array[object]	Custom transformation functions

Response Examples

Example Configuration

Complete Policy Configuration Example

The following example shows a complete policy configuration with workflows, conditions, and actions:

{
  "workflows": [
    {
      "name": "Active Employees",
      "description": "Triggered when any active employee is active",
      "trigger_type": "TRIGGER_STRING",
      "trigger_string": "employment_status eq \"ACTIVE\"",
      "continuous_sync": true,
      "conditions_on_success": [
        {
          "name": "sync",
          "condition_type": "work_location eq \"China\"",
          "actions_to_run": [
            {
              "name": "ChinaEmployeeGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        },
        {
          "name": "sync",
          "condition_type": "work_location eq \"US\"",
          "actions_to_run": [
            {
              "name": "UsEmployeeGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        },
        {
          "name": "sync",
          "condition_type": "department eq \"Sales\" and manager eq true",
          "actions_to_run": [
            {
              "name": "SalesManagerGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "UsEmployeeGroups",
      "description": "Adds US employees to defined access profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id1>", "<access_profile_id2>"]
      }
    },
    {
      "name": "ChinaEmployeeGroups",
      "description": "Adds China employees to defined access profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id3>", "<access_profile_id4>"]
      }
    },
    {
      "name": "SalesManagerGroups",
      "description": "Adds Sales Manager profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id5>"]
      }
    }
  ],
  "attribute_common_transformers": []
}

Configuration Structure Explanation

Workflows define when the policy triggers:

• trigger_string: SCIM filter expression that determines when the workflow activates

• conditions_on_success: Array of conditions evaluated when the trigger is met

• continuous_sync: Whether to continuously monitor for changes

Conditions specify additional criteria:

• condition_type: SCIM filter expression for the specific condition

• actions_to_run: Actions executed when this condition is met

Actions define what happens when conditions are satisfied:

• type: Currently supports MANAGE_RELATIONSHIPS and SYNC_IDENTITIES

• config: Action-specific configuration object

• For MANAGE_RELATIONSHIPS: Defines access profiles to assign/remove

Troubleshooting Common Issues

404 Errors When Updating Policy Configuration

If you receive a 404 error when attempting to update a policy configuration, verify:

1. Policy ID is correct: Confirm the policy exists by first calling GET /api/private/lifecycle_management/policies/{policy_id}

2. Version number exists: Check the current_version_number from the GET response and ensure you're using the correct version

3. Endpoint path is correct: Ensure you're using /versions/ (plural) in the URL path

Common mistake: Using /version/{number} instead of /versions/{number} in the endpoint path.

Policy Version Not Found

If you get errors about version not found:

• Always use the current_version_number from the Get Policy response

• Policy versions are auto-created and managed by the system - you can't create arbitrary version numbers

• If you need to work with a different version, you may need to publish or manage the policy state first

Configuration Validation Errors

When policy configuration updates fail validation:

1. Check JSON structure: Ensure your configuration object matches the expected schema

2. Verify action types: Confirm action type values are valid (e.g., MANAGE_RELATIONSHIPS, SYNC_IDENTITIES)

3. Validate SCIM expressions: Test trigger strings and condition strings for proper SCIM syntax

4. Confirm referenced IDs: Ensure access profile IDs and other references exist in your environment

Request Body Format

Ensure your request body follows this structure:

{
  "value": {
    "policy_id": "your-policy-id",
    "config": {
      "workflows": [...],
      "actions": [...],
      "attribute_common_transformers": [...]
    }
  }
}

The configuration should be nested within a value.config object, not sent as the root object.