Update Review Status

curl --request PUT \
  --url https://use.hoop.dev/api/reviews/{id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "APPROVED",
  "force_review": false,
  "rejection_reason": "This command is not allowed in production."
}
'

{
  "access_duration": 0,
  "access_request_rule_name": "default-access-request-rule",
  "created_at": "2024-07-25T15:56:35.317601Z",
  "force_approval_groups": [
    "sre-team"
  ],
  "id": "9F9745B4-C77B-4D52-84D3-E24F67E3623C",
  "min_approvals": 2,
  "rejection_reason": "This command is not allowed in production.",
  "review_groups_data": [
    {
      "forced_review": false,
      "group": "sre",
      "id": "20A5AABE-C35D-4F04-A5A7-C856EE6C7703",
      "review_date": "2024-07-25T19:36:41Z",
      "reviewed_by": {
        "email": "john.wick@bad.org",
        "id": "D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90",
        "name": "John Wick",
        "slack_id": "U053ELZHB53"
      },
      "status": "APPROVED"
    }
  ],
  "revoke_at": "",
  "session": "35DB0A2F-E5CE-4AD8-A308-55C3108956E5",
  "time_window": {
    "configuration": {
      "end_time": "18:00",
      "start_time": "09:00"
    },
    "type": "time_range"
  }
}

Reviews

Update Review Status

Update the status of a review resource by its resource ID or session ID. This endpoint is used to approve, reject, or revoke reviews for session execution requests.

Overview

When a user interacts with a session, a review resource is automatically created containing the configured review groups, each initially set to PENDING status. All groups must be approved before the session can be executed.

The review status updates affect each review group based on the caller’s context. Once all groups are APPROVED, or if any group becomes REJECTED or REVOKED, the overall resource status updates accordingly.

Review Groups

Review groups contain individual review entries that must be completed by authorized users from specific groups. Each entry represents a required approval from a designated reviewer group.

Initial State

When a review is created, each group entry is populated with the following structure:

{
    "id": "aaa257be-5cc9-401d-ae7e-18ae806d366a",
    "group": "banking",
    "status": "PENDING",
    "reviewed_by": null,
    "review_date": null
}

Completed Review State

After a review is completed, the entry includes the status, review timestamp, and reviewer information:

{
    "id": "a546dfba-d917-4c2b-bc38-7852a7932573",
    "group": "banking",
    "status": "REJECTED",
    "reviewed_by": {
        "id": "17e4ff1a-104c-482c-be68-3c01bfc7028e",
        "name": "John Doe",
        "email": "john.doe@domain.tld",
        "slack_id": ""
    },
    "review_date": "2025-05-27T16:40:05.519754143Z"
}

Review States

User-Controlled States

These states are set directly by reviewers:

APPROVED - The resource has been approved by the reviewer
REJECTED - The resource is rejected and cannot be updated further
REVOKED - The resource is revoked and cannot be updated further

System-Controlled States

These states are managed automatically by the gateway:

PENDING - Initial state when the review is created
PROCESSING - Session is being executed; review cannot be updated
EXECUTED - Session completed successfully; review cannot be updated
UNKNOWN - Session executed but outcome is indeterminate

General Rules

Review Permissions

Reviews can only be performed when the resource status is PENDING or APPROVED
Resource owners cannot self-approve - approval requires another member of the same group
Users are only eligible to review if they are not the resource owner or are administrators

Multi-Group Reviews

If a user belongs to multiple groups, separate review entries are updated for each group
All group reviews must be completed before session execution

Status Transitions

Setting any review to REJECTED immediately changes the overall resource status and prevents further updates
APPROVED reviews can still be changed to REJECTED or REVOKED at any time by the resource owner or administrators
Once a review reaches REJECTED or REVOKED the resource is considered as immutable and it cannot be updated again

Final States

Reviews in PROCESSING, EXECUTED, or UNKNOWN states are immutable and cannot be modified.

PUT

reviews

{id}

Update Review Status

curl --request PUT \
  --url https://use.hoop.dev/api/reviews/{id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "APPROVED",
  "force_review": false,
  "rejection_reason": "This command is not allowed in production."
}
'

{
  "access_duration": 0,
  "access_request_rule_name": "default-access-request-rule",
  "created_at": "2024-07-25T15:56:35.317601Z",
  "force_approval_groups": [
    "sre-team"
  ],
  "id": "9F9745B4-C77B-4D52-84D3-E24F67E3623C",
  "min_approvals": 2,
  "rejection_reason": "This command is not allowed in production.",
  "review_groups_data": [
    {
      "forced_review": false,
      "group": "sre",
      "id": "20A5AABE-C35D-4F04-A5A7-C856EE6C7703",
      "review_date": "2024-07-25T19:36:41Z",
      "reviewed_by": {
        "email": "john.wick@bad.org",
        "id": "D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90",
        "name": "John Wick",
        "slack_id": "U053ELZHB53"
      },
      "status": "APPROVED"
    }
  ],
  "revoke_at": "",
  "session": "35DB0A2F-E5CE-4AD8-A308-55C3108956E5",
  "time_window": {
    "configuration": {
      "end_time": "18:00",
      "start_time": "09:00"
    },
    "type": "time_range"
  }
}

Path Parameters

string

required

Resource identifier of the review

Body

application/json

The request body resource

status

enum<string>

required

The reviewed status

APPROVED - Approve the review resource
REJECTED - Reject the review resource
REVOKED - Revoke an approved review

Available options:

APPROVED,

REJECTED,

REVOKED

Example:

"APPROVED"

force_review

boolean

Example:

false

rejection_reason

string

Example:

"This command is not allowed in production."

time_window

object

Show child attributes

Response

access_duration

integer

default:1800000000000

read-only

The amount of time (nanoseconds) to allow access to the connection. It's valid only for jit type reviews

Example:

0

access_request_rule_name

string

read-only

The name of the access request rule that triggered this review, if null means it was triggered by the review plugin

Example:

"default-access-request-rule"

created_at

string

read-only

The time the resource was created

Example:

"2024-07-25T15:56:35.317601Z"

force_approval_groups

string[]

read-only

Groups that can force approve sessions for this review

Example:

["sre-team"]

string<uuid>

read-only

Resource identifier

Example:

"9F9745B4-C77B-4D52-84D3-E24F67E3623C"

min_approvals

integer

read-only

The minimum number of approvals required for this review

Example:

2

rejection_reason

string

read-only

The reason provided by the reviewer when rejecting this review

Example:

"This command is not allowed in production."

review_groups_data

object[]

read-only

Contains the groups that requires to approve this review

Show child attributes

revoke_at

string

read-only

The time when this review was revoked

Example:

""

session

string<uuid>

read-only

The id of session

Example:

"35DB0A2F-E5CE-4AD8-A308-55C3108956E5"

status

enum<string>

The status of the review

PENDING - The resource is waiting to be reviewed
APPROVED - The resource is fully approved
REJECTED - The resource is fully rejected
REVOKED - The resource was revoked after being approved
PROCESSING - The review is being executed
EXECUTED - The review was executed
UNKNOWN - Unable to know the status of the review

Available options:

PENDING,

APPROVED,

REJECTED,

REVOKED,

PROCESSING,

EXECUTED,

UNKNOWN

time_window

object

The time window configuration that can execute the session

Show child attributes

type

enum<string>

The type of the review

onetime - Represents a one time execution
jit - Represents a time based review

Available options:

onetime,

jit

Get Review Update Review Status By Sid

⌘I