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

Authorizations

Responses

200

OK

application/json

default

Default error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/preview/awf/automations HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
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"
            }
          ],
          "fallback_reviewers": [
            {
              "user_type": "text",
              "id": "text",
              "email": "text",
              "name": "text"
            }
          ],
          "reviewers_managers_for_approval_levels": [
            1
          ]
        },
        "display_style": 1,
        "display_text": "text"
      }
    }
  ]
}

Update Automation

• Endpoint: /api/preview/awf/automations

• Method: PUT

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

put

Authorizations

Body

Responses

200

OK

application/json

Responseobject

default

Default error response

application/json

put

HTTPcURLJavaScriptPython

PUT /api/preview/awf/automations HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 569

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

{}

Create Automation

• Endpoint: /api/preview/awf/automations

• Method: POST

• Description: Creates a new Automation.

post

Authorizations

Body

namestringOptional

descriptionstringOptional

priorityinteger · int32Optional

Responses

200

OK

application/json

default

Default error response

application/json

post

HTTPcURLJavaScriptPython

POST /api/preview/awf/automations HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 547

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

{
  "id": "text"
}

Get Automation

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

• Method: GET

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

get

Authorizations

Path parameters

idstringRequired

Responses

200

OK

application/json

default

Default error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/preview/awf/automations/{id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
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"
          }
        ],
        "fallback_reviewers": [
          {
            "user_type": "text",
            "id": "text",
            "email": "text",
            "name": "text"
          }
        ],
        "reviewers_managers_for_approval_levels": [
          1
        ]
      },
      "display_style": 1,
      "display_text": "text"
    }
  }
}

Delete Automation

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

• Method: DELETE

• Description: Deletes a specific Automation by its ID.

delete

Authorizations

Path parameters

idstringRequired

Responses

200

OK

application/json

Responseobject

default

Default error response

application/json

delete

HTTPcURLJavaScriptPython

DELETE /api/preview/awf/automations/{id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
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

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

OK

application/json

Responseobject

default

Default error response

application/json

post

HTTPcURLJavaScriptPython

POST /api/preview/awf/automations:attach HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
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

Path parameters

workflow_idstringRequired

Responses

200

OK

application/json

default

Default error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/preview/awf/automations:attached/{workflow_id} HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
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"
              }
            ],
            "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
    }
  ]
}

Detach Automations

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

• Method: POST

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

post

Authorizations

Body

Detaches an automation from one or all workflows

idstringOptional

workflow_idstringOptional

allbooleanOptional

Responses

200

OK

application/json

Responseobject

default

Default error response

application/json

post

HTTPcURLJavaScriptPython

POST /api/preview/awf/automations:detach HTTP/1.1
Host: 
Authorization: Bearer Bearer <API key>
Content-Type: application/json
Accept: */*
Content-Length: 45

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

{}