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"
  }
}

{
  "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.

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"
  }
}

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.

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

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

/api/preview/awf/automations

Authorizations

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/preview/awf/automations' \
  --header 'Authorization: Bearer Bearer <API key>'

200

default

200

{
  "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"
            }
          ],
          "fallback_reviewers": [
            {
              "user_type": "text",
              "id": "text",
              "email": "text",
              "name": "text"
            }
          ],
          "reviewers_managers_for_approval_levels": [
            1
          ]
        },
        "display_style": 1,
        "display_text": "text"
      }
    }
  ]
}

OK

Update Automation

• Endpoint: /api/preview/awf/automations

• Method: PUT

• Description: Updates an existing Automation. The full Automation object is required.

put

/api/preview/awf/automations

Authorizations

Body

valueobject

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/preview/awf/automations' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json' \
  --data '{"value":{"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"}],"fallback_reviewers":[{"user_type":"text","id":"text","email":"text","name":"text"}],"reviewers_managers_for_approval_levels":[1]},"display_style":1,"display_text":"text"}}}'

200

default

200

{}

OK

Create Automation

• Endpoint: /api/preview/awf/automations

• Method: POST

• Description: Creates a new Automation.

post

/api/preview/awf/automations

Authorizations

Body

namestring

descriptionstring

priorityinteger · int32

attachment_behaviorobject

criteriaobject

actionobject

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/preview/awf/automations' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json' \
  --data '{"attachment_behavior":{},"criteria":{},"action":{"reviewer_assignment":{"users_manager":true,"resource_managers":true,"reviewers":[{"user_type":"text","id":"text","email":"text","name":"text"}],"fallback_reviewers":[{"user_type":"text","id":"text","email":"text","name":"text"}],"reviewers_managers_for_approval_levels":[1]}}}'

200

default

200

{
  "id": "text"
}

OK

Get Automation

• Endpoint: /api/preview/awf/automations/{id}

• Method: GET

• Description: Get details for a single Automation by ID.

get

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

Authorizations

Path parameters

idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/preview/awf/automations/{id}' \
  --header 'Authorization: Bearer Bearer <API key>'

200

default

200

{
  "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"
          }
        ],
        "fallback_reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text"
          }
        ],
        "reviewers_managers_for_approval_levels": [
          1
        ]
      },
      "display_style": 1,
      "display_text": "text"
    }
  }
}

OK

Delete Automation

• Endpoint: /api/preview/awf/automations/{id}

• Method: DELETE

• Description: Deletes a specific Automation by its ID.

delete

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

Authorizations

Path parameters

idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/api/preview/awf/automations/{id}' \
  --header 'Authorization: Bearer Bearer <API key>'

200

default

200

{}

OK

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

/api/preview/awf/automations:attach

Authorizations

Body

idstring

workflow_idstring

allboolean

opt_inboolean

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/preview/awf/automations:attach' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json'

200

default

200

{}

OK

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

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

Authorizations

Path parameters

workflow_idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/preview/awf/automations:attached/{workflow_id}' \
  --header 'Authorization: Bearer Bearer <API key>'

200

default

200

{
  "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"
              }
            ],
            "fallback_reviewers": [
              {
                "user_type": "text",
                "id": "text",
                "email": "text",
                "name": "text"
              }
            ],
            "reviewers_managers_for_approval_levels": [
              1
            ]
          },
          "display_style": 1,
          "display_text": "text"
        }
      },
      "opt_in": true
    }
  ]
}

OK

Detach Automations

• Endpoint: /api/preview/awf/automations:detach

• Method: POST

• Description: Detach one or all Automations from an Access Review Workflow.

post

/api/preview/awf/automations:detach

Authorizations

Body

idstring

workflow_idstring

allboolean

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/preview/awf/automations:detach' \
  --header 'Authorization: Bearer Bearer <API key>' \
  --header 'Content-Type: application/json'

200

default

200

{}

OK