Automations API

Get, create, update, delete, and attach Intelligent Automations.

Use these operations to manage Access Review Automations and associate them with individual workflows.

Automations apply changes (such as approve, sign-off, add a note, or apply visual indicators) to Certification rows based on historical certification data, or a filter on the current results. They can run by default or on an opt-in basis when a certification is created.

Example Automations

{
  "id": "e48dd2c8-3633-463b-a477-0177a942b5a6",
  "name": "Highlight inactive sources",
  "description": "Highlight rows where the source account is inactive",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "source.is_active eq false",
    "mutable_filter": ""
  },
  "action": {
    "display_style": "HIGHLIGHT",
    "display_text": "Source account is inactive",
    "highlight_color": "#FF6B35"
  }
}

{
  "id": "f59ee3d9-4744-574c-b588-1288b0942c7c",
  "name": "Reject privileged account access",
  "description": "Suggest reject for admin or root accounts",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "(destination.name eq \"admin\") OR (source.name eq \"root\")",
    "mutable_filter": ""
  },
  "action": {
    "display_style": "SUGGEST_REJECT",
    "display_text": "Privileged account detected - review carefully"
  }
}

For more information about this feature see Intelligent Automations.

You will need an API token with root team or administrator permissions to manage Automations.

Key Concepts

When working with the Automations API, it is important to understand the relationship between three identifiers:

ID Type

Description

Scope

Automation ID

Unique identifier for a reusable Automation rule

Global (can be attached to multiple workflows)

Workflow ID

Unique identifier for an Access Review configuration

Defines the query, reviewers, and settings for reviews

Certification ID

Unique identifier for a specific Access Review instance created from a workflow

A single review cycle with results to act upon

At an API level,

An Automation is a reusable rule that can be attached to one or more Workflows
A Workflow (review configuration) defines how reviews are created and can have multiple Certifications over time
A Certification is a single instance of a review where Automations run against the results

Error handling and conflicts

The following rules apply when an Automation run encounters an issue:

If Automation processing fails for any result, the Automation run stops and no further Automations are applied.
When Automations fail, the Certification is still considered complete and non-errored. The Automation run will have an error status and message.

Results are considered the same when the entities and relationships are exactly equal (including data source IDs). If a conflict occurs with Automations trying to change the same mutable field:

Each change must update the field to the same value. The action log entry will contain notes (if supplied) for each action.
Automations changing a field to differing values are unresolvable conflicts and skipped, but will not interrupt the Automation run.

Automation Object Schema

An Automation consists of attachment_behavior rules, filter criteria, and an action to apply:

{
  "id": "string",
  "name": "string",
  "description": "string",
  "priority": 0,
  "attachment_behavior": {
    "attach_to_new_workflows": boolean,
    "opt_in": boolean
  },
  "criteria": {
    "filter": "string",
    "mutable_filter": "string"
  },
  "action": {
    // For modification actions:
    "decision": "string",
    "signed_off_state": "string",
    "notes": "string",
    "reviewer_assignment": null,

    // OR for display actions:
    "display_style": "string",
    "display_text": "string",
    "highlight_color": "string"
  }
}

Each Automation object has the fields:

id (String): Unique identifier for the Automation.
name (String): Name of the Automation.
description (String): A brief description of the Automation.
priority (Integer): Priority value of the Automation (not currently supported).

`attachment_behavior` (Object)

Defines if the Automation is available for all workflows, and whether it is optional:

attach_to_new_workflows (Boolean): Indicates whether to automatically attach to new and existing workflows.
opt_in (Boolean): If true Operators can pick the automation when creating a Workflow. If false the automation is enabled by default.

`criteria` (Object)

Specifies filters for conditionally updating results:

filter (String): A SCIM filter specifying a source or destination attribute with support for complex expressions using AND, OR, and parentheses for grouping. Examples:
- Simple filter: source.is_active eq false
- Complex filter: (source.name sw "A" OR source.name sw "B") AND destination.is_active eq true
mutable_filter (String): A filter on a previous result mutable field using the syntax previous.attribute. Example: "previous.decision eq "RESULT_DECISION_ACCEPTED""

Similarly to Smart Actions, Automations can update results based on a source or destination attribute (such as activity status). Filters use the syntax source.attribute or destination.attribute.

Filtering by Joined Node Attributes

When an Access Review configuration includes IdP or HRIS enrichment, you can filter on enriched entity attributes in Automations. Reference joined nodes by their alias directly (e.g., idp.attribute), not using joined_nodes.idp.attribute.

For complete guidance on finding aliases, filter syntax, and examples, see Using Enrichment Data in Automations.

Early Access: Filtering by joined node attributes in Automations is currently in early access. Contact Veza Support for the latest status.

Filtering by Mutable Fields

Mutable filters in Automations use the syntax previous.decision, previous.notes and previous.signed_off_state to refer to historical row data. The possible values are:

decision:
- "RESULT_DECISION_UNKNOWN"
- "RESULT_DECISION_NONE"
- "RESULT_DECISION_ACCEPTED"
- "RESULT_DECISION_REJECTED"
- "RESULT_DECISION_FIXED"
notes: string
signed_off_state:
- "UNKNOWN"
- "NOT_SIGNED_OFF"
- "SIGNED_OFF"

`action` (Object)

Action the Automation will apply to matching results:

decision (String): Decision code for the action.
signed_off_state (String): Sign off state code.
notes (String): Notes the automation will apply.
display_style (String): Visual indicator to apply to matching rows:
- HIGHLIGHT: Highlight the row
- SUGGEST_ACCEPT: Mark the row as suggested for acceptance
- SUGGEST_REJECT: Mark the row as suggested for rejection
display_text (String): Custom message to show when display_style is set
highlight_color (String): Hex color code for custom row highlighting (e.g., #FF0000, #00FF00). Only applies when display_style is HIGHLIGHT. Must be a valid 6-digit hex color in the format #RRGGBB. If omitted, the default highlight color is used.

Note: When using display_style actions, you cannot set decision, signed_off_state, notes, or reviewer_assignment fields.

Possible decisions and numeric codes are:

UNKNOWN (0)
NONE (1)
ACCEPTED (2)
REJECTED (3)
FIXED (4)

Signed Off State can be:

UNKNOWN_SIGNED_OFF = 0;
NOT_SIGNED_OFF = 1;
SIGNED_OFF = 2;

`reviewer_assignment` (Object)

The preview API does not currently support Reviewer assignment.

Preview API Documentation

Use the endpoints documented below to create and manage automations:

List Automations

Endpoint: /api/preview/awf/automations
Method: GET
Description: Returns all Automations and configuration details.

Returns all Automations in a values array.

get

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Responses

200

application/json

default

Default error response

application/json

get

/api/preview/awf/automations

GET /api/preview/awf/automations HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "priority": 1,
      "attachment_behavior": {
        "attach_to_new_workflows": true,
        "opt_in": true
      },
      "criteria": {
        "filter": "text",
        "mutable_filter": "text"
      },
      "action": {
        "decision": 1,
        "signed_off_state": 1,
        "notes": "text",
        "reviewer_assignment": {
          "users_manager": true,
          "resource_managers": true,
          "reviewers": [
            {
              "user_type": "text",
              "id": "text",
              "email": "text",
              "name": "text",
              "alternate_email": "text"
            }
          ],
          "fallback_reviewers": [
            {
              "user_type": "text",
              "id": "text",
              "email": "text",
              "name": "text",
              "alternate_email": "text"
            }
          ],
          "reviewers_managers_for_approval_levels": [
            1
          ]
        },
        "display_style": 1,
        "display_text": "text",
        "highlight_color": "text"
      }
    }
  ]
}

Update Automation

Endpoint: /api/preview/awf/automations
Method: PUT
Description: Updates an existing Automation. The full Automation object is required.

put

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body

Responses

200

application/json

objectOptional

default

Default error response

application/json

put

/api/preview/awf/automations

PUT /api/preview/awf/automations HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 644

{
  "value": {
    "id": "text",
    "name": "text",
    "description": "text",
    "priority": 1,
    "attachment_behavior": {
      "attach_to_new_workflows": true,
      "opt_in": true
    },
    "criteria": {
      "filter": "text",
      "mutable_filter": "text"
    },
    "action": {
      "decision": 1,
      "signed_off_state": 1,
      "notes": "text",
      "reviewer_assignment": {
        "users_manager": true,
        "resource_managers": true,
        "reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text",
            "alternate_email": "text"
          }
        ],
        "fallback_reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text",
            "alternate_email": "text"
          }
        ],
        "reviewers_managers_for_approval_levels": [
          1
        ]
      },
      "display_style": 1,
      "display_text": "text",
      "highlight_color": "text"
    }
  }
}

{}

Create Automation

Endpoint: /api/preview/awf/automations
Method: POST
Description: Creates a new Automation.

post

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body

namestringOptional

descriptionstringOptional

priorityinteger · int32Optional

Responses

200

application/json

idstringOptional

default

Default error response

application/json

post

/api/preview/awf/automations

POST /api/preview/awf/automations HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 622

{
  "name": "text",
  "description": "text",
  "priority": 1,
  "attachment_behavior": {
    "attach_to_new_workflows": true,
    "opt_in": true
  },
  "criteria": {
    "filter": "text",
    "mutable_filter": "text"
  },
  "action": {
    "decision": 1,
    "signed_off_state": 1,
    "notes": "text",
    "reviewer_assignment": {
      "users_manager": true,
      "resource_managers": true,
      "reviewers": [
        {
          "user_type": "text",
          "id": "text",
          "email": "text",
          "name": "text",
          "alternate_email": "text"
        }
      ],
      "fallback_reviewers": [
        {
          "user_type": "text",
          "id": "text",
          "email": "text",
          "name": "text",
          "alternate_email": "text"
        }
      ],
      "reviewers_managers_for_approval_levels": [
        1
      ]
    },
    "display_style": 1,
    "display_text": "text",
    "highlight_color": "text"
  }
}

{
  "id": "text"
}

Get Automation

Endpoint: /api/preview/awf/automations/{id}
Method: GET
Description: Get details for a single Automation by ID.

get

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Path parameters

idstringRequired

Responses

200

application/json

default

Default error response

application/json

get

/api/preview/awf/automations/{id}

GET /api/preview/awf/automations/{id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "id": "text",
    "name": "text",
    "description": "text",
    "priority": 1,
    "attachment_behavior": {
      "attach_to_new_workflows": true,
      "opt_in": true
    },
    "criteria": {
      "filter": "text",
      "mutable_filter": "text"
    },
    "action": {
      "decision": 1,
      "signed_off_state": 1,
      "notes": "text",
      "reviewer_assignment": {
        "users_manager": true,
        "resource_managers": true,
        "reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text",
            "alternate_email": "text"
          }
        ],
        "fallback_reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text",
            "alternate_email": "text"
          }
        ],
        "reviewers_managers_for_approval_levels": [
          1
        ]
      },
      "display_style": 1,
      "display_text": "text",
      "highlight_color": "text"
    }
  }
}

Delete Automation

Endpoint: /api/preview/awf/automations/{id}
Method: DELETE
Description: Deletes a specific Automation by its ID.

delete

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Path parameters

idstringRequired

Responses

200

application/json

objectOptional

default

Default error response

application/json

delete

/api/preview/awf/automations/{id}

DELETE /api/preview/awf/automations/{id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}

Attach Automations

Endpoint: /api/preview/awf/automations:attach
Method: POST
Description: Enable an Automation for a specific workflow, or all workflows.

Attach one or all Automations to a single workflow by specifying the:

id (String): Single Automation ID.
workflow_id (String): ID of the workflow to associate Automations with.
all (boolean): If True, attaches all existing Automations to the Workflow.
opt_in (boolean): If False the Automation can be selected when creating a certification. Otherwise, operators can enable it when creating certifications.

post

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body

Attaches an automation to one or all workflows Attach will succeeds if the automation is already attached and will update the "opt_in" if necessary

idstringOptional

workflow_idstringOptional

allbooleanOptional

opt_inbooleanOptional

Responses

200

application/json

objectOptional

default

Default error response

application/json

post

/api/preview/awf/automations:attach

POST /api/preview/awf/automations:attach HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "id": "text",
  "workflow_id": "text",
  "all": true,
  "opt_in": true
}

{}

List attached Workflow Automations

Endpoint: /api/preview/awf/automations:attached/{workflow_id}
Method: GET
Description: Returns all Automations eligible to run on Certifications for a given Workflow id.

get

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Path parameters

workflow_idstringRequired

Responses

200

application/json

default

Default error response

application/json

get

/api/preview/awf/automations:attached/{workflow_id}

GET /api/preview/awf/automations:attached/{workflow_id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "automation": {
        "id": "text",
        "name": "text",
        "description": "text",
        "priority": 1,
        "attachment_behavior": {
          "attach_to_new_workflows": true,
          "opt_in": true
        },
        "criteria": {
          "filter": "text",
          "mutable_filter": "text"
        },
        "action": {
          "decision": 1,
          "signed_off_state": 1,
          "notes": "text",
          "reviewer_assignment": {
            "users_manager": true,
            "resource_managers": true,
            "reviewers": [
              {
                "user_type": "text",
                "id": "text",
                "email": "text",
                "name": "text",
                "alternate_email": "text"
              }
            ],
            "fallback_reviewers": [
              {
                "user_type": "text",
                "id": "text",
                "email": "text",
                "name": "text",
                "alternate_email": "text"
              }
            ],
            "reviewers_managers_for_approval_levels": [
              1
            ]
          },
          "display_style": 1,
          "display_text": "text",
          "highlight_color": "text"
        }
      },
      "opt_in": true
    }
  ]
}

Detach Automations

Endpoint: /api/preview/awf/automations:detach
Method: POST
Description: Detach one or all Automations from an Access Review Workflow.

post

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Body

Detaches an automation from one or all workflows

idstringOptional

workflow_idstringOptional

allbooleanOptional

Responses

200

application/json

objectOptional

default

Default error response

application/json

post

/api/preview/awf/automations:detach

POST /api/preview/awf/automations:detach HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "id": "text",
  "workflow_id": "text",
  "all": true
}

{}

PreviousGet Access Graph NextAccess Review Settings

Last updated 1 month ago

Was this helpful?

hashtagExample Automations

hashtagKey Concepts

hashtagError handling and conflicts

hashtagAutomation Object Schema

hashtagattachment_behavior (Object)

hashtagcriteria (Object)

hashtagFiltering by Joined Node Attributes

hashtagFiltering by Mutable Fields

hashtagaction (Object)

hashtagreviewer_assignment (Object)

hashtagPreview API Documentation

hashtagList Automations

hashtagUpdate Automation

hashtagCreate Automation

hashtagGet Automation

hashtagDelete Automation

hashtagAttach Automations

hashtagList attached Workflow Automations

hashtagDetach Automations

Example Automations

Key Concepts

Error handling and conflicts

Automation Object Schema

`attachment_behavior` (Object)

`criteria` (Object)

Filtering by Joined Node Attributes

Filtering by Mutable Fields

`action` (Object)

`reviewer_assignment` (Object)

Preview API Documentation

List Automations

Update Automation

Create Automation

Get Automation

Delete Automation

Attach Automations

List attached Workflow Automations

Detach Automations