Update or create a plugin connection resource

Upsert Plugin Connection

Hoop.dev - the only access gateway with data masking

Secure gateway access to your infrastructure with AI-powered security

Getting Started

Zero-config DLP policies that automatically mask sensitive data in real-time at the protocol layer

AI Data Masking

Transform your data management from unstructured to controlled, with powerful permission rules that safeguard and streamline your resources

Access Control

Protect your infrastructure with intelligent access controls

Guardrails

Automate operational tasks with reusable, auditable templates

Runbooks

Secure and centralized secrets management for your infrastructure

Secrets Management

Record and playback terminal sessions and entire databases connections.

Session Recording

Superpower your web experience with a way to nativelly connect to your databases and services without the need of our command line

Desktop App

Install and configure the hoop.dev CLI to interact with your applications.

Command Line

Proxy an SSH Server to remote hosts in your private network.

Secure Shell (SSH)

Architecture

Managing License for your Hoop Installation

License Management

Agents

Connections

Review sessions directly from your Slack workspace.

Slack

Hoop.dev can integrate with Microsoft Teams, sending messages to a channel when a particular event happens.

Teams

Automate change management and security workflows by integrating Jira with your infrastructure access requests.

Jira

Integrate with Svix to have wehbooks/SIEM properly configured.

Svix

Database Resource Discovery and Automatic Connection Creation.

AWS Connect

List Agent Keys

Create an agent key in a DSN format: `grpc(s)://<name>:<key>@<grpc-host>:<grpc-port>?mode=standard|embedded`.
This key is used to deploy agents and expose internal resources from your infra-structure

Create Agent Key

Remove an agent key. It will invalidate a running agent

Delete Agent Key

Exchanges and validates the authorization code for an access token after being redirect by the external provider.
A success authentication will redirect the user back to the default redirect url provided in the /login route.

In case of error it will include the query string `error=unexpected_error` when redirecting.


OIDC | Login Callback

Generate a new access token  to interact with the API that expires in 12 hours.

Local | Login

It registers a new user in the system with the provided email and password. Additionall users are only registered when they are invited by an existing admin user.

Local | Register User

Returns the login url to perform the signin on the identity provider

OIDC | Login

It redirects the user to the redirect URL with a JWT access token on success. A success authentication will redirect the user back to the default redirect url provided in the /saml/login route. In case of error it will include the query string error=<description> when redirecting.

SAML | Login Callback

Returns the login url to perform the signin on the identity provider.

SAML | Login

Signup anonymous authenticated user. This endpoint is only used for multi tenant setups.

OIDC | Signup

List Connections

The connection resource allows exposing internal services from your internal infra structure to users.

### Types of Connections

The definition of this resource represent how clients will be able to interact with internal resources.

Each type/subtype may represent a distinct implementation:

- `application/<subtype>` - An alias to map distinct types of shell applications (e.g.: python, ruby, etc)
- `application/tcp` - Forward TCP connections

    This type requires the following environment variables:
    - `HOST`: ip or dns of the internal service
    - `PORT`: the port of the internal service

- `custom` - Any custom shell application
- `database/<subtype>` - Allow connecting to databases through multiple clients (Webapp, cli, IDE's)

Each `<subtype>` has distinct environment variables that are allowed to be configured, refer to our [documentation](https://hoop.dev/docs) for more information.

### Tags

Tags are key/value pairs that are attached to objects such as Connections. Tags are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system.

```json
{
    "connection_tags": {
        "environment": "production",
        "component": "backend"
    }
}
```

Equality- or inequality-based requirements allow filtering by tags keys and values. Matching objects must satisfy all of the specified tag constraints, though they may have additional tags as well. Three kinds of operators are admitted `=`,`!=`. The first represent equality, while the last represents inequality. For example:

```
environment = production
tier != frontend
```

The former selects all resources with key equal to `environment` and value equal to `production`. The latter selects all resources with key equal to `tier` and value distinct from `frontend`. One could filter for resources in production excluding frontend using the comma operator: environment=production,tier!=frontend


Create Connection

List Connection Tags

Get Connection

Update Connection

Get Table Columns

List all available databases for a database connection

List Databases

List tables from a database without column details

List Database Tables

Delete Connection

List Data Masking Rules

Create Data Masking Rule

Get Data Masking Rule

Update Data Masking Rule

Delete Data Masking Rule

List DB Role Jobs

It creates a job that performs the provisioning of default database roles

Create Database Role Job

Get DB Role Job

Update IAM Access Key or set a region when using IAM instance role

Update IAM Access Key

Delete IAM Access Key

It obtain the aws identity of the instance role or credentials

Get Caller Identity

It list all AWS accounts associated with the access key credentials

List AWS Accounts

List Database Instances

Proxy to OpenAI chat completions `/vi/chat/completions`

OpenAI Chat Completions

Updates a feature configuration. It will report if this feature is available in the user info endpoint.

Feature Update

Get Webhooks Dashboard

List Guard Rail Rules

Create Guard Rail Rules

Get Guard Rail Rules

Update Guard Rail Rules

Delete a Rule

Reports if the service is working properly

HealthCheck

Update Org License

Sign a new license for a customer. This route is for internal use only

Sign License

Get Public Server Info

Get Authentication Configuration

Update Authentication Configuration

Generate API Key

Get Server Miscellaneous Configuration

Update server miscellaneous configuration

Update Server Miscellaneous Configuration

Get Server Info

Get Jira integration for the organization

Get Jira Integration

Update the Jira integration for the organization

Update Jira Integration

Create a new Jira integration for the organization

Create Jira Integration

Get objects from the Jira Service Management (JSM) Assets API

Get Asset Objects

List Issue Templates

Create Issue Templates

Get Issue Templates

Update Issue Templates

Delete Issue Templates

Get the organization key to run with `hoop run` command line

Get Org Key

Create the organization key to run with `hoop run` command line.

Create Org Key

Revoke Org Key

List Plugins

Create Plugin

Get Plugin

Update Plugin resource. The `config` and `name` attributes are immutable for this endpoint.

Update Plugin

Update the Plugin resource top level configuration.

Update Plugin Config

Get Plugin Connection

Delete Plugin Connection

Start a execution using a Runbook as input. If the connection has a JIRA issue template configured, it will create a JIRA issue.

Runbook Exec

List Runbooks By Connection

List Runbooks

Send a connect request to the client. A successful response indicates the client has stablished a connection.
If the connection resource has the review enabled, it returns a successful response containing the link of the review in the `Localtion` header.

ProxyManager Connect

Send a disconnect request. The transport layer will disconnect the connected client asynchronously

ProxyManager Disconnect

ProxyManager Status

The report payload groups sessions by info types and by a custom field (`group_by`) provided by the client.
The items returns data containing the sum of redact fields performed by a given info type aggregated by the `group_by` attribute.

Session Reports

Get review resource by the id or session id

Get Review

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:

```json
{
    "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:

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

## 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.

Update Review Status

Update Review Status By Sid

List Service Accounts

Create a service account that is associated with a identity provider client

Create Service Account

Update a service account that is associated with a identity provider client

Update Service Account

Get UserInfo

List Users

Inviting a user will pre configure user definitions like display name, profile picture, groups or his slack id

Invite User

List User Groups

Create User Group

Delete User Group

Patch User Slack ID

Get User

Update User

Delete User

List Sessions

This endpoint performs ad-hoc executions. It will wait 50 seconds for a sucessful response (200), otherwise return an Accepted status code (202) meaning the execution will be held asynchronously. The outcome could be obtained later on by fetching the resource using the attribute `id`.

The payload of this request is used with the Connection resource to construct the command to be executed in the remote agent.
- The `script` attribute is passed as stdin to the Connection resource `command` attribute.
- The attribute `client_args` is appended to the suffix of the `command`.

For example, the following connection:

```json
{
  "name": "bash-connection",
  "command": ["/bin/bash"],
  "type": "custom"
}
```

With the following payload:

```json
{
  "script": "echo 'hello world'",
  "client_args": ["-x"],
  "connection": "bash-connection"
}
```

Will perform an ad-hoc shell execution as:

```sh
/bin/bash -x <<EOF
echo 'hello world'
EOF
```


Exec

Get a session by id. This endpoint returns a conditional response

- When the query string `extension` is present it will return a payload containing a link to download the session

```json
{
  "download_url": "http://127.0.0.1:8009/api/sessions/<id>/download?token=<token>&extension=csv&newline=1&event-time=0&events=o,e",
  "expire_at": "2024-07-25T15:56:35.317601Z",
}
```

- Fetching the endpoint without any query string returns the payload documented for this endpoint
- The attribute `event_stream` will be rendered differently if the request contains the query string `event_stream` with the values `utf8` or `base64`.

```json
{
  (...)
  "event_stream": ["hello world"]
  (...)
}
```

The attribute `metrics` contains the following structure:

```json
{
  "data_masking": {
    "err_count": 0,
    "info_types": {
      "EMAIL_ADDRESS": 1
    },
    "total_redact_count": 1,
    "transformed_bytes": 31
  },
  "event_size": 356
}
```


Get Session

Download Session

Kill Session

Update Session Metadata

Reviewed Exec

Community

Blog

API Reference

Get started

Sign In

Add an intelligent security layer with real-time command reviews and just-in-time access controls

Reviews Overview

Real-time command review and approval workflow for enhanced security

Command Reviews

Interact with the JIT console or execute ad-hoc scripts

Just-in-Time Reviews

Get started with Hoop.dev's powerful web interface for managing secure infrastructure access

Web App Overview

Learn how to set up secure connections to your resources through the Hoop.dev web interface

Creating Connections

Learn how to control and organize access to your connections through user groups and permissions

Managing Access

Learn how to track and audit connection usage through the Sessions interface

Monitoring Sessions

A Postgres connection is a native type, allowing for the auditing of queries and redaction of their output. It facilitates a local TCP connection without requiring a password.

PostgreSQL

Connect to a private mysql instance from your favorite IDE

Agents

Authentication

Connections

Data Masking Rules

AWS

Features

Guard Rails

Server Management

Jira

Organization Management

Plugins

Runbooks

Proxy Manager

Reports

Reviews

User Management

Sessions

Session

Upsert Plugin Connection

Path Parameters

Body

Response