> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Approval Status By Sid > Update the status of an approval request resource by its resource ID or session ID. This endpoint is used to approve, reject, or revoke approval requests for session execution requests. ## Overview When a user interacts with a session, an approval request resource is automatically created containing the configured approver groups, each initially set to `PENDING` status. **All groups must be approved before the session can be executed.** The approval status updates affect each approver 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. ## Approver Groups Approver groups contain individual approval entries that must be completed by authorized users from specific groups. Each entry represents a required approval from a designated approver group. ### Initial State When an approval request is created, each group entry is populated with the following structure: ```json { "id": "aaa257be-5cc9-401d-ae7e-18ae806d366a", "group": "banking", "status": "PENDING", "reviewed_by": null, "review_date": null } ``` ### Completed Approval State After an approval entry is completed, it includes the status, decision timestamp, and approver information: ```json { "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" } ``` ## Approval States ### User-Controlled States These states are set directly by approvers: - **`APPROVED`** - The resource has been approved by the approver - **`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 approval request is created - **`PROCESSING`** - Session is being executed; approval request cannot be updated - **`EXECUTED`** - Session completed successfully; approval request cannot be updated - **`UNKNOWN`** - Session executed but outcome is indeterminate - **`EXPIRED`** - A sidecar approval request passed its `expires_at` before it was decided or used; nothing was released. Only a control plane sets it ## General Rules ### Approval Permissions - An approval request the user cannot get with `GET /reviews/{id}` answers `404`, the same as an approval request that does not exist - Approvals can only be decided 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 approve if they are **not the resource owner** or are **administrators** ### Multi-Group Approvals - If a user belongs to multiple groups, separate approval entries are updated for each group - All group approvals must be completed before session execution ### Status Transitions - Setting any approval to `REJECTED` immediately changes the overall resource status and prevents further updates - `APPROVED` approval requests can still be changed to `REJECTED` at any time by the resource owner or administrators - `REVOKED` applies only to an `APPROVED` approval request of type `jit`, or to an `APPROVED` approval request a sidecar filed (it has a `listener_name`). A sidecar approval request can be revoked until the sidecar uses the approval; after that it is `EXECUTED` and the request answers `400`. A revoke of any other approval request answers `400` - Once an approval request reaches `REJECTED` or `REVOKED` the resource is considered as immutable and it cannot be updated again - A decision on a sidecar approval request past its `expires_at` answers `400` (`approval request expired`), and the approval request is `EXPIRED` ### Final States Approval requests in `PROCESSING`, `EXECUTED`, `UNKNOWN`, or `EXPIRED` states are immutable and cannot be modified. ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json put /sessions/{session_id}/approval openapi: 3.0.3 info: contact: email: help@hoop.dev name: Help url: https://help.hoop.dev description: >- Hoop.dev is an access gateway for databases and servers with an API for packet manipulation license: name: MIT url: https://opensource.org/license/mit termsOfService: https://hoop.dev/docs/legal/tos title: Hoop Api version: 1.244.0 servers: - url: https://use.hoop.dev/api security: [] tags: - description: > Hoop implements Oauth2 and OIDC protocol to authenticate users in the system. To obtain a valid access token users need to authenticate in their own identity provider which is generated as a JSON response to the endpoint `http(s)://use.hoop.dev/api/login`. The identity provider them redirects the user to the callback endpoint containing the access token. The recommended approach of obtaining an access token is by visiting the Webapp main's page or using the **Hoop command line**. Example: ```sh hoop config create --api-url https://use.hoop.dev # save the token after authenticating at $HOME/.hoop/config.toml hoop login # show token information hoop config view --raw ``` With an access token you could use any HTTP client to interact with the documented endpoints. The token must be sent through the `Authorization` header. Example: ```sh # obtain the current configuration of the server curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer $ACCESS_TOKEN" ``` name: Authentication - description: > Users are active and assigned to the default organization when they signup. A user could be set to an inactive state preventing it from accessing the platform, however it’s recommended to manage the state of users in the identity provider. - The `sub` claim is used as the main identifier of the user in the platform. - The profile of the user is derived from the id_token claims `email` and `name`. When a user authenticates for the first time, it performs an automatic signup that persist the profile claims along with it’s unique identifier. ​ ### Groups Groups allows defining who may access or interact with certain resources. - For connection resources it’s possible to define which groups has access to a specific connection, this is enforced when the Access Control feature is enabled. - For review resources, it’s possible to define which groups are allowed to approve an execution, this is enforced when the Review feature is enabled. > This resource could be managed manually via Webapp or propagated by the identity provider via ID Token. In this mode, groups are sync when a user performs a login. ### Roles - The `admin` group is a special role that grants full access to all resources This role should be granted to users that are responsible for managing the Gateway. All other users are regular, meaning that they can access their own resources and interact with connections. name: User Management - name: Machine Identities - description: Routes used to manage and obtain information about the runtime server. name: Server Management - description: Features available in the gateway. See also **Plugin** resources. name: Features - description: >- Proxy manager endpoints controls how clients connect via gRPC in the gateway. These endpoints are meant to be used when a client is initialized via `hoop proxy-manager`. name: Proxy Manager - name: Connections - name: Agents - name: Sidecars - name: Runbooks - name: Guard Rails - name: Approvals - name: Sessions - name: Organization Management - name: Reports - description: > Security audit log API. Only users in the **admin** group can access these endpoints. Audit log entries record security-relevant events (who performed an action, when, on which resource, and whether it succeeded). Use the list endpoint with filters to query by actor, resource type, action, outcome, or date range. Results are paginated and ordered by `created_at` descending. name: Audit Logs paths: /sessions/{session_id}/approval: put: tags: - Approvals summary: Update Approval Status By Sid description: >- Update the status of an approval request resource by its resource ID or session ID. This endpoint is used to approve, reject, or revoke approval requests for session execution requests. ## Overview When a user interacts with a session, an approval request resource is automatically created containing the configured approver groups, each initially set to `PENDING` status. **All groups must be approved before the session can be executed.** The approval status updates affect each approver 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. ## Approver Groups Approver groups contain individual approval entries that must be completed by authorized users from specific groups. Each entry represents a required approval from a designated approver group. ### Initial State When an approval request is created, each group entry is populated with the following structure: ```json { "id": "aaa257be-5cc9-401d-ae7e-18ae806d366a", "group": "banking", "status": "PENDING", "reviewed_by": null, "review_date": null } ``` ### Completed Approval State After an approval entry is completed, it includes the status, decision timestamp, and approver information: ```json { "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" } ``` ## Approval States ### User-Controlled States These states are set directly by approvers: - **`APPROVED`** - The resource has been approved by the approver - **`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 approval request is created - **`PROCESSING`** - Session is being executed; approval request cannot be updated - **`EXECUTED`** - Session completed successfully; approval request cannot be updated - **`UNKNOWN`** - Session executed but outcome is indeterminate - **`EXPIRED`** - A sidecar approval request passed its `expires_at` before it was decided or used; nothing was released. Only a control plane sets it ## General Rules ### Approval Permissions - An approval request the user cannot get with `GET /reviews/{id}` answers `404`, the same as an approval request that does not exist - Approvals can only be decided 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 approve if they are **not the resource owner** or are **administrators** ### Multi-Group Approvals - If a user belongs to multiple groups, separate approval entries are updated for each group - All group approvals must be completed before session execution ### Status Transitions - Setting any approval to `REJECTED` immediately changes the overall resource status and prevents further updates - `APPROVED` approval requests can still be changed to `REJECTED` at any time by the resource owner or administrators - `REVOKED` applies only to an `APPROVED` approval request of type `jit`, or to an `APPROVED` approval request a sidecar filed (it has a `listener_name`). A sidecar approval request can be revoked until the sidecar uses the approval; after that it is `EXECUTED` and the request answers `400`. A revoke of any other approval request answers `400` - Once an approval request reaches `REJECTED` or `REVOKED` the resource is considered as immutable and it cannot be updated again - A decision on a sidecar approval request past its `expires_at` answers `400` (`approval request expired`), and the approval request is `EXPIRED` ### Final States Approval requests in `PROCESSING`, `EXECUTED`, `UNKNOWN`, or `EXPIRED` states are immutable and cannot be modified. parameters: - description: Resource identifier of the session in: path name: session_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/openapi.ReviewRequest' description: The request body resource required: true x-originalParamName: request responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.Review' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Bad Request '403': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Internal Server Error components: schemas: openapi.ReviewRequest: properties: force_review: example: false type: boolean rejection_reason: example: This command is not allowed in production. type: string status: allOf: - $ref: '#/components/schemas/openapi.ReviewRequestStatusType' description: |- The approval status * APPROVED - Approve the approval request * REJECTED - Reject the approval request * REVOKED - Revoke an approved request example: APPROVED time_window: $ref: '#/components/schemas/openapi.ReviewSessionTimeWindow' required: - status type: object openapi.Review: properties: access_duration: default: 1800000000000 description: >- The amount of time (nanoseconds) to allow access to the connection. It's valid only for `jit` type approval requests example: 0 readOnly: true type: integer access_request_rule_name: description: >- The name of the access request rule that triggered this approval request, if null means it was triggered by the review plugin example: default-access-request-rule readOnly: true type: string approval_ttl_sec: description: >- The time a sidecar approval lasts, in seconds, copied from the rule at filing. Absent with no limit or on an approval request from a connection example: 600 readOnly: true type: integer connection: allOf: - $ref: '#/components/schemas/openapi.ReviewConnection' description: >- The connection the approval request was filed against. On a sidecar approval request, the resource that mirrors the listener; absent while the organization has no mirror for it readOnly: true created_at: description: The time the resource was created example: '2024-07-25T15:56:35.317601Z' readOnly: true type: string expires_at: description: >- The deadline of a sidecar approval request: to decide while PENDING, to use the approval once APPROVED. Absent with no limit or on an approval request from a connection example: '2024-07-25T16:11:35.000Z' readOnly: true type: string force_approval_groups: description: Groups that can force approve sessions for this approval request example: - sre-team items: type: string readOnly: true type: array id: description: Resource identifier example: 9F9745B4-C77B-4D52-84D3-E24F67E3623C format: uuid readOnly: true type: string listener_name: description: >- The sidecar listener this approval request is bound to. Absent on an approval request that came from a connection example: appdb readOnly: true type: string min_approvals: description: The minimum number of approvals required for this approval request example: 2 readOnly: true type: integer rejection_reason: description: >- The reason provided by the approver when rejecting this approval request example: This command is not allowed in production. readOnly: true type: string review_groups_data: description: Contains the groups that must approve this request items: $ref: '#/components/schemas/openapi.ReviewGroup' readOnly: true type: array revoke_at: description: The time when this approval request was revoked example: '' readOnly: true type: string session: description: The id of session example: 35DB0A2F-E5CE-4AD8-A308-55C3108956E5 format: uuid readOnly: true type: string sidecar_id: description: >- The sidecar that filed this approval request. Absent on an approval request that came from a connection example: 5F5E5C6E-6C3A-4E9A-9E8B-2D6A7F1B0C4D format: uuid readOnly: true type: string status: allOf: - $ref: '#/components/schemas/openapi.ReviewStatusType' description: >- The status of the approval request * PENDING - The resource is waiting for approval * APPROVED - The resource is fully approved * REJECTED - The resource is fully rejected * REVOKED - The resource was revoked after being approved * PROCESSING - The approval request is being executed * EXECUTED - The approval request was executed * UNKNOWN - Unable to know the status of the approval request * EXPIRED - A sidecar approval request passed its deadline; it never releases the statement time_window: allOf: - $ref: '#/components/schemas/openapi.ReviewSessionTimeWindow' description: The time window configuration that can execute the session readOnly: true type: allOf: - $ref: '#/components/schemas/openapi.ReviewType' description: |- The type of the approval request * onetime - Represents a one time execution * jit - Represents a time based approval enum: - onetime - jit readOnly: true type: object openapi.HTTPError: properties: message: example: the error description type: string type: object openapi.ReviewRequestStatusType: enum: - APPROVED - REJECTED - REVOKED type: string x-enum-varnames: - ReviewStatusRequestApprovedType - ReviewStatusRequestRejectedType - ReviewStatusRequestRevokedType openapi.ReviewSessionTimeWindow: properties: configuration: additionalProperties: type: string example: end_time: '18:00' start_time: '09:00' type: object type: allOf: - $ref: '#/components/schemas/openapi.ReviewTimeWindowType' enum: - time_range required: - configuration - type type: object openapi.ReviewConnection: properties: id: description: The resource identifier example: 20A5AABE-C35D-4F04-A5A7-C856EE6C7703 readOnly: true type: string name: description: The name of the connection example: pgdemo readOnly: true type: string type: object openapi.ReviewGroup: properties: forced_review: description: Indicates if this group forced the approval example: false readOnly: true type: boolean group: description: The group to approve this request example: sre readOnly: true type: string id: description: The resource identifier example: 20A5AABE-C35D-4F04-A5A7-C856EE6C7703 format: uuid readOnly: true type: string review_date: description: The date of this decision example: '2024-07-25T19:36:41Z' readOnly: true type: string reviewed_by: allOf: - $ref: '#/components/schemas/openapi.ReviewOwner' description: The approver readOnly: true status: allOf: - $ref: '#/components/schemas/openapi.ReviewRequestStatusType' description: |- The approval status * APPROVED - Approve the approval request * REJECTED - Reject the approval request * REVOKED - Revoke an approved request example: APPROVED type: object openapi.ReviewStatusType: enum: - PENDING - APPROVED - REJECTED - REVOKED - PROCESSING - EXECUTED - UNKNOWN - EXPIRED type: string x-enum-varnames: - ReviewStatusPending - ReviewStatusApproved - ReviewStatusRejected - ReviewStatusRevoked - ReviewStatusProcessing - ReviewStatusExecuted - ReviewStatusUnknown - ReviewStatusExpired openapi.ReviewType: enum: - jit - onetime type: string x-enum-varnames: - ReviewTypeJit - ReviewTypeOneTime openapi.ReviewTimeWindowType: enum: - time_range type: string x-enum-varnames: - ReviewTimeWindowTypeTimeRange openapi.ReviewOwner: properties: email: description: The email of the owner example: john.wick@bad.org readOnly: true type: string id: description: The resource identifier example: D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90 format: uuid readOnly: true type: string name: description: The display name of the owner example: John Wick readOnly: true type: string slack_id: description: The Slack ID of the owner example: U053ELZHB53 readOnly: true type: string type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.