Approval request lifecycle

An approval request is created automatically whenever a user triggers an action governed by an approval action. It records the pending decision and tracks the request through review, approval or denial, and execution.

Request statuses

Status	Description
pending	Awaiting a decision from a human reviewer or policy evaluation.
approved	Manually approved by a reviewer.
auto_approved	Automatically approved because a policy passed and on_policy_success is set to approve.
auto_denied	Automatically denied because a policy failed and on_policy_fail is set to deny.
denied	Manually denied by a reviewer.
cancelled	Cancelled before a decision was reached.
expired	No decision was made before the reply window closed.

Execution statuses

Once a request reaches approved or auto_approved, an execution window opens. The execution_status tracks the state of the underlying action.

Execution status	Description
pending	Approved but not yet executed.
executing	Execution is in progress.
success	The action executed successfully.
failed	Execution encountered an error.
expired	The execution window closed before the action was triggered.

Expiration windows

note

Expiration windows are currently used when users request access to secret parameter values. If that's your use case, check out Accessing secret values for a full example.

Two time limits control how long each phase can last. Both are configured on the approval action, not on individual requests.

• time_to_reply: How long (in milliseconds) approvers have to respond. If the window closes without a decision, the request status moves to expired.
• allowed_time_to_execute: How long (in milliseconds) after approval the action can be executed. If execution doesn't happen within this window, the execution_status moves to expired.

Checking request status

To retrieve the current status of an approval request, send a GET request to the approval endpoint:

CLI

np approval read --id 1234

cURL

curl -L 'https://api.nullplatform.com/approval/1234' \
-H 'Authorization: Bearer <token>'

The response includes both status and execution_status, so you can tell at a glance where the request is in its lifecycle.

What's next

Create a checklist to automate approval decisions and reduce the number of requests that require manual review. Policies still work for the actions that use them, but they'll be deprecated in favor of checklists.