Create a new access review certification from an existing workflow.

Overview

Use dynamic_information to filter certification results to specific identities at creation time. This enables you to use a broad query at the workflow level, and then scope individual reviews to certain identities when creating the certification.

Identity IDs and types are sourced from the Veza Authorization Graph and must match existing graph node values from your integrated identity providers.

Endpoint

POST /api/preview/awf/certifications

Request Body

Dynamic Information

The dynamic_information parameter allows you to filter certification results to specific user identities at creation time.

Identity Object

Reviewer Assignment

The reviewer_assignment and reviewer_assignment_second_level objects configure how reviewers are assigned to certification rows.

Response

{
  "certification_id": "b2562ef3-a4b3-4b30-8a45-1ba36f945d10"
}

Examples

Basic Certification

Create a certification using the latest data:

curl -X POST "$VEZA_URL/api/preview/awf/certifications" \
  -H "authorization: Bearer $VEZA_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "workflow_id": "b9dc2586-5f30-4462-b6be-53f62debc40f",
    "name": "Q4 2025 Access Review",
    "data_source": 0
  }'

Dynamic Filtering (Joiner/Mover/Leaver)

Use dynamic_information to scope a certification to specific identities. For mover scenarios, include previous_manager_id:

curl -X POST "$VEZA_URL/api/preview/awf/certifications" \
  -H "authorization: Bearer $VEZA_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "workflow_id": "b9dc2586-5f30-4462-b6be-53f62debc40f",
    "name": "Department Transfer Review",
    "data_source": 0,
    "dynamic_information": {
      "identities": [
        {
          "id": "00u1a2b3c4d5e6f7g8h9",
          "type": "OktaUser",
          "previous_manager_id": "00umgr123456789"
        }
      ]
    }
  }'

Multi-Level Review

Create a certification with multi-level approval requirements:

curl -X POST "$VEZA_URL/api/preview/awf/certifications" \
  -H "authorization: Bearer $VEZA_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "workflow_id": "b9dc2586-5f30-4462-b6be-53f62debc40f",
    "name": "High-Risk Access Review",
    "data_source": 0,
    "reviewer_assignment": {
      "resource_managers": true
    },
    "reviewer_assignment_second_level": {
      "users_manager": true
    },
    "final_approval_level": 2
  }'

Identity Types

Use the graph node type that corresponds to your integrated IdP:

Identity IDs and types must match the values stored in the Veza Authorization Graph. You can find these values by querying the graph or viewing entity details in the Veza UI.

See Also

• List Workflows - Get workflow IDs

• List Certifications - View created certifications

• Workflow Parameters - Complete parameter reference

Define filter-based actions that reviewers can apply to certifications results with a matching attribute or status.

Reviewers can view and apply custom actions from the Review interface by clicking Smart Action > Prepared Actions.

• Add smart action definition

  • Mutable fields and mutable filters

• Remove a smart action definition

• List smart action definitions

• Update a smart action definition

Add smart action definition

Create a smart action definition, globally or for a single Workflow.

A certification result includes all source and destination node properties discovered or added by Veza. You can specify a SCIM filter to select the results to affect, for example:

Example request:

curl -X POST "https://{{veza_url}}/api/preview/awf/smart_action_definitions" \
-H 'authorization: Bearer {{access_token}}' \
-d '{
  "apply_to_all_rows": "false",
  "description": "Reject users where the user `is active` value is not `true`",
  "filter": "source.is_active ne \"true\"",
  "mutable_fields": {
    "decision": "RESULT_DECISION_REJECTED"
  },
  "mutable_filter": "",
  "name": "Reject inactive users",
  "workflow_id": ""
}'

The filter can apply to any source or destination node property.

When apply_to_all_rows is true and no other filter criteria is specified, the action will run on all certification results.

Mutable fields and mutable filters

Mutable fields contain result attributes that are not sourced from Access Graph metadata. Use mutable_fields to apply changes to a result, and mutable_filter to filter results based on decision or sign-off state:

{
  "apply_to_all_rows": "false",
  "description": "Sign off on all rejected rows",
  "filter": "",
  "mutable_fields": {
    "signed_off_state": "SIGNED_OFF"
  },
  "mutable_filter": "decision eq \"RESULT_DECISION_REJECTED\"",
  "name": "Sign off rejected rows",
  "workflow_id": ""
}

Remove a smart action definition

Delete a prepared action by definition id.

List smart action definitions

Returns an array of smart action definitions. By default, this endpoint lists all definitions. If a workflow_id is specified, only definitions for that workflow are included in the response.

Update a smart action definition

Alter a smart action definition by specifying the id and an array of values to change.

Enable or disable self-review prevention. When self-review prevention is enabled, users are prevented from being assigned as reviewers for rows that relate to their own access and permissions.

Parameters

The value can be either an integer or string:

• SELF_REVIEWER_CHECKING_DISABLED = 1 (or "SELF_REVIEWER_CHECKING_DISABLED" as string)

• SELF_REVIEWER_CHECKING_ENABLED = 2 (or "SELF_REVIEWER_CHECKING_ENABLED" as string)

An optional workflow_id parameter allows configuring self-review prevention per review configuration, overriding the global setting for that configuration. When workflow_id is omitted, the request reads or writes the global setting.

Examples

Example using string value (global):

{
    "value": "SELF_REVIEWER_CHECKING_DISABLED"
}

Example using integer value (global):

{
    "value": 1
}

Example enabling self-review prevention for a specific review configuration:

{
    "value": "SELF_REVIEWER_CHECKING_ENABLED",
    "workflow_id": "8ae1c414-3a76-46cb-950a-925316b3f264"
}

When a workflow_id is provided on a GET request, Veza returns the configuration-specific setting if one exists, or falls back to the global setting.

Example GET request (per review configuration):

curl -L -X GET 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/self_reviewer_settings?workflow_id=8ae1c414-3a76-46cb-950a-925316b3f264' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'

Example cURL request (global):

curl -L -X PUT 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/self_reviewer_settings' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 1
  }'

Example cURL request (per review configuration):

curl -L -X PUT 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/self_reviewer_settings' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 2,
    "workflow_id": "8ae1c414-3a76-46cb-950a-925316b3f264"
  }'

Get Self Review Settings

Set Self Review Settings

This setting is configurable on the Access Reviews > Settings page. Enable Auto-Expire overdue reviews to automatically expire reviews that aren't completed by the due date.

Enables or disable expiration of overdue reviews. By default, overdue reviews are not expired and remain available to reviewers. When expiration is enabled, the review will be "expired" when it becomes overdue. An expired review is read-only and is not shown to reviewers.

Parameters

The value can be True or False.

Get Expire Overdue Reviews Setting

Set Expire Overdue Reviews Setting

These endpoints enable listing workflows, listing certifications, getting certification results, and updating certifications. They can be used to programmatically retrieve workflow and certification details, and update certification rows with a decision or note, such as ticket number.

These endpoints also provide utility functionality, such as managing the reviewer deny list, populating results with webhook response info, and customizing quick filters, smart actions, and help pages.

Core Workflow Operations

APIs for Veza Access Reviews are subject to change, and as such are provided with the /preview API collection. Use the appropriate prefix when calling the API, for example, your-org.vezacloud.com/api/preview/.

Quick start

First, save your and Veza base URL as environment variables:

Get all workflows and IDs:

Use a workflow id to get active and pending certifications for that workflow:

The response will include certification details, including the certification ids.

Using a certification id, you can get results for the certification, including entity attributes:

Update a certification result row with a note:

List, create, and delete saved filters, globally or for a single workflow. Reviewers can pick from available quick filters under Certification Filters > Saved Filters.

Requests require a for authentication.

Examples

Add a quick filter

Add a quick filter by specifying an optional workflow_id and a single source or destination node property, corresponding to a Review interface column.

Filters can also apply to abstract_permissions or concrete_permissions (see example response).

Valid filter operators are:

• co "contains"

• eq "equals"

• ne "not equals"

With a workflow_id specified, the filter will only apply to certifications on that workflow. Otherwise, reviewers can apply the quick filter to any certification:

A successful response will contain the filter id, for example:

List all quick filters

Including a workflow_id in the query returns quick filters with a matching workflow_id and quick filters with no workflow_id:

Example response:

Remove quick filter by quick filter id

Use these APIs to configure for Veza Access Reviews.

The settings that can be configured by a Veza administrator are:

ForceUpdateAwfResults allows administrators to modify results more than normally allowed, such as changing sign-off status, or changing a row's decision after a certification expires.

The API token used for this request must be created for a user with the

Use these operations to add and manage help pages for access reviewers, and customize pop-up messages when a review starts, or when rows are signed off.

Create help page

Add custom help messages for reviewers by providing the plain text template_body, name, and an existing workflow_id and usage where the template will apply. All reviews (certifications) for the configuration (workflow) will use the new template.

Template usage

The usage field determines how and when the help page will be visible to users. It must be one of the following values:

• HELP_PAGE: Reviewers can access help pages from reviewer's interface by clicking the User Guide icon. The help page will also appear when viewing the review for the first time.

• REVIEW_START: Opens when reviewers start a review.

• SIGN_OFF

Only one help page can exist at a time for a given workflow and usage. You can manage global help pages by using 00000000-0000-0000-0000-000000000000 as the workflow_id. Global help pages for each usage will apply to all reviews for all configurations.

Template formatting

The template can use markdown and placeholders, for example:

See for more information about placeholders.

Example request:

List help pages

Get all configured help page templates.

Example response:

Get help page

Returns the current help page template for an existing workflow_id and usage.

• The usage parameter must be specified. For the existing help page template, the usage value should be HELP_PAGE.

• To retrieve the tenant-wide default template (if it was set), use an all-zero UUID (00000000-0000-0000-0000-000000000000) for the workflow_id.

Example request:

Get review help page

Returns the current template for a given certification id.

Example request:

Example response:

Delete help page

Permanently remove the help page template for a workflow_id and usage. It will no longer apply to reviews for using the configuration, specified by workflow_id.

• The usage parameter must be specified. For the existing help page template, the usage value should be HELP_PAGE.

• To clear the tenant-wide default template, use an all-zero UUID for the workflow_id: 00000000-0000-0000-0000-000000000000.

Example request:

Update help page

PUT {{veza_url}}/api/preview/awf/help_page_templates

Update the help page for the specified workflow_id and usage:

• To add a tenant-wide default template, use an all-zero UUID for the workflow_id: 00000000-0000-0000-0000-000000000000.

• Updating a template now uses a plain text template_body, instead of a base64-encoded string.

Example request:

API reference for the Action Allow List feature. For configuration guidance and how it works, see Action Allow List.

Role Requirements

Principals

Both users and groups can be added to the allow list. A user is permitted if their user ID is directly on the list, or if any Veza group they belong to is on the list.

Each principal is specified as an object with a type and id:

All IDs must be Veza internal UUIDs. Email addresses and usernames are not supported.

To look up a user's UUID:

• Administration console: Go to Administration > Users, click the user's name, and copy the UUID from their profile page.

• Users API: Use the to list users and locate the id field in the response.

To look up a group's UUID:

• Groups API: Use GET /api/private/groups to list groups and locate the id field for the target group. Use the filter query parameter to narrow by name (e.g., ?filter=name eq 'Your Group Name').

Allowed Actions

The allowed_action field controls which restricted operations the principal is permitted to perform. Specify one or both values:

API Reference

Check Whether the Allow List Is Enabled

GET /api/private/workflows/access/settings/action_allowlist_enabled

Returns the current enabled state of the allow list.

Example:

Response:

Enable or Disable the Allow List

PUT /api/private/workflows/access/settings/action_allowlist_enabled

Enable or disable the allow list globally. When disabled, existing RBAC governs access to all review operations.

Request body:

Set enabled to true to enable or false to disable.

Example (enable):

Example (disable):

Add Principals to the Allow List

POST /api/private/workflows/access/action_allowlist

Add one or more users or groups to the allow list. A single request can include multiple principals of mixed types.

Request body:

Example (add a user for both actions):

Example (add a group):

Remove Principals from the Allow List

POST /api/private/workflows/access/action_allowlist:delete

Remove one or more principals from the allow list. Uses the same request shape as the add endpoint.

Request body:

Example:

List All Permitted Principals

GET /api/private/workflows/access/action_allowlist

Returns all users and groups currently on the allow list. Each entry represents one principal–action pair; a principal with two allowed actions appears as two separate entries.

Example:

Response:

Check Whether a User Is Permitted

GET /api/private/workflows/access/action_allowlist/{user_id}

Returns the resolved allowed actions for the specified user, including permissions inherited from group memberships. Pass a user UUID — passing a group UUID will return an empty allowed_actions array rather than an error.

Example:

Response:

Returns an empty array if the user is not on the list and belongs to no permitted groups.

Enable or disable the "auto-complete" feature. When auto-complete is enabled, a review will automatically be completed once all rows have a signed-off decision, or a non-rejected signed-off decision, depending on the "Completion Allowed Settings."

Parameters

Possible values are:

• AUTO_COMPLETE_UNKNOWN

• AUTO_COMPLETE_ENABLED

• AUTO_COMPLETE_DISABLED

Example

Get Review Auto-Complete Settings

Set Review Auto-Complete Settings

Configure predefined notes as menu options when reviewers approve or reject rows. This feature can be configured globally for all reviews or specifically for individual review configurations. When configured for a specific review configuration (using workflow_id), those settings override any global predefined notes.

The predefined notes appear as selectable options in the notes dialog when making decisions, suggesting standardized responses alongside free-form text entry.

Parameters

The request body accepts:

An Admin or Operator user can complete a review by clicking the "Complete Review" button.

Once a review is marked as "completed," it becomes read-only and is no longer visible to reviewers. By default, a review can be completed when all rows have a signed-off decision.

This API allows you to modify this behavior, enabling a review to be completed at any time, or only when all rows are signed off with a non-rejected decision. The latter option is useful if your organization prefers to complete reviews only after all rejected access has been remediated.

Parameters