---
sidebar_label: Approval actions
doc_id: 5029e8dd-760c-4474-bdc2-19d0ad053874
description: >-
  Configure approval actions to control when approval processes trigger for
  deployments, scopes, and other operations.
keywords:
  - approval process
  - deployment control
  - access management
  - workflow automation
  - governance
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Approval actions

## What is an approval action?

An approval action specifies the entities and actions requiring approval, and their outcomes. It determines:

- when an approval process is triggered, such as deploying to a production environment or creating a new scope.
- what the outcome of that action is: approved, denied, or flagged for manual review.
- at what level in your organization this action applies.

## Available entities and actions

Approval actions apply to the following entities and actions:

| Entity           | Actions                                                                       |
| ---------------- | ----------------------------------------------------------------------------- |
| `deployment`     | `deployment:create`                                                           |
| `scope`          | `scope:create`, `scope:recreate`, `scope:write`, `scope:delete`, `scope:stop` |
| `service:action` | `service:action:create`                                                       |
| `parameter`      | `parameter:read-secrets`                                                      |
| `action_item`    | `action_item:resolve`, `action_item:defer`, `action_item:reject`              |

Each **entity** is a resource type, while each **action** describes an operation performed on that entity. For example, `deployment` defines the entity and `deployment:create` refers to creating a deployment.

The `action_item` entity gates how developers transition [action items](/docs/action-items): resolving, deferring, or rejecting them. Unlike `deployment` or `scope`, it doesn't take dimensions, so you scope these approvals through the NRN alone. See [Configure and manage action items](/docs/action-items/configure-and-manage#require-approval-to-transition-items) for an end-to-end example.

## Create an approval action

The first step to configure approvals is to create an approval action. You can use our CLI or API. Send a [POST request](/docs/api/approval-action-create) to our Approval endpoint.

<Tabs
defaultValue="action-cli"
values={[
{ label: 'CLI', value: 'action-cli' },
{ label: 'cURL', value: 'action-curl' },
]}>

<TabItem value="action-cli">

```bash
np approval action create
  --body '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "entity": "deployment",
    "action": "deployment:create",
    "dimensions": {
      "environment": "production",
      "country": "us"
    },
    "on_policy_success": "manual",
    "on_policy_fail": "manual"
  }'
```

</TabItem>
<TabItem value="action-curl">

```bash
curl -L -X POST 'https://api.nullplatform.com/approval/action' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "entity": "deployment",
    "action": "deployment:create",
    "dimensions": {
        "environment": "production",
        "country": "us"
    },
    "on_policy_success": "manual",
    "on_policy_fail": "manual"
}
```

</TabItem>
</Tabs>

:::info Default behavior for approval requests
If you don’t include `on_policy_success` and `on_policy_fail` in your request, the approval will default to **manual review**.
:::

#### What this approval action does

This action ensures that when a user attempts to **create a deployment in a production environment** at the organization level `organization=1:account=2:namespace=3:application=4`, the request requires **manual approval**. It must be reviewed and explicitly approved or denied before proceeding.

#### Example response

For a successful request, you'll get a response like this:

```json
{
  "id": 98765, // Save the action ID for the next steps
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "entity": "deployment",
  "action": "deployment:create",
  "on_policy_success": "manual",
  "on_policy_fail": "manual"
}
```

This ensures that requests to create deployments are evaluated and either approved or flagged for manual review based on policy results.

:::tip
The `id` field contains the unique approval action ID. Be sure to save it, as you'll need it in the next steps.
:::

## Using policies to enhance approval actions

Approval **actions work on their own** to specify approvals for specific entities and actions.

However, you can link them to [policies](/docs/approvals/policies) to add conditions that define **when** approval is needed. This allows you to enforce rules that align approvals with your organization’s requirements, such as time-based rules or conditions on the size of the resource being created.

:::warning Upcoming deprecation

Policies will be deprecated in favor of [checklists](/docs/approvals/checklists). Attach a checklist to any new action instead. [Specs and actions](/docs/approvals/checklist-specs) shows how to connect one. If you want to migrate policies to checklists, [reach out to the nullplatform team](/docs/support).

:::

## What's next

Now that you've created your approval actions, the next step is to [set up a notification channel](/docs/approvals/set-up-notifications) so that reviewers are alerted when a request is pending.