Resource Roles

Connections that expose internal services to authorized users through the Hoop gateway

In the Web App, these are called Resource Roles. In the API, the same objects are called connections. They refer to the same thing: a named, typed configuration that exposes an internal service through a Hoop agent.

Connection Types

Every connection has a type and an optional subtype.

Database (type: "database")

Connections that implement native database wire protocols. Hoop intercepts queries and can enforce masking, guardrails, and access policies on the traffic.

Subtype	Protocol
postgres	PostgreSQL wire protocol
mysql	MySQL protocol
mongodb	MongoDB Wire Protocol
mssql	Microsoft SQL Server
oracledb	Oracle Database

Application (type: "application")

Connections to networked services and processes.

Subtype	Description
httpproxy	Forwards HTTP/HTTPS traffic to an upstream service
tcp	Raw TCP forwarding
ssh	SSH tunneling

Custom (type: "custom")

Arbitrary shell command execution. Use this type when your resource doesn’t fit a standard protocol. The command field defines what runs when a session opens.

Agent Binding

Each connection is bound to an agent via the agent_id field. The connection’s status reflects the agent’s reachability:

• online — the agent is connected and the resource is accessible
• offline — the agent is not connected or the resource is unreachable

If no agent_id is set on the connection, it inherits the agent from the associated resource.

Credentials

Connection secrets (database passwords, API tokens, hostnames) are stored as environment variables attached to the connection. In the API, they are submitted under a secret object with "envvar:KEY" keys, base64-encoded:

{
  "secret": {
    "envvar:HOST": "bXlkYi5leGFtcGxlLmNvbQ==",
    "envvar:PORT": "NTQzMg==",
    "envvar:USER": "YWRtaW4=",
    "envvar:PASS": "c3VwZXJzZWNyZXQ="
  }
}

The agent resolves these environment variables at runtime when opening a session.

Access Modes

Each connection exposes up to three interaction modes, each independently enabled or disabled:

Mode	Description
exec	Run a command and receive output (non-interactive)
connect	Open an interactive session (e.g., a database shell)
runbooks	Execute pre-defined runbook scripts against the connection

Features Per Connection

Hoop features are attached to individual connections via the plugin system. When a connection is created, a default set of plugins is automatically enabled. Additional features can be configured on a per-connection basis:

Feature	Plugin	What it does
Session Recording	audit	Always active; records all session activity
Live Data Masking	dlp	Redacts sensitive patterns (emails, credit cards, etc.) in output
Access Requests	review	Holds execution pending approval from a designated reviewer group
Guardrails	—	Enforces input/output rules attached to the connection
Access Control	access_control	Restricts which user groups can see and use the connection
Runbooks	runbooks	Enables runbook execution on the connection
Webhooks / SIEM	webhooks	Forwards session lifecycle events to external endpoints
Slack Notifications	slack	Sends Slack messages for access request events

See Plugins for a full reference.

Creating Connections

Web App

Navigate to Resource Roles in the sidebar, then click New Resource Role. Select the type and fill in the required fields.

API

curl -X POST https://<your-gateway>/api/connections \
  -H "Api-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-postgres",
    "type": "database",
    "subtype": "postgres",
    "agent_id": "<agent-id>",
    "secret": {
      "envvar:HOST": "<base64-encoded-host>",
      "envvar:PORT": "<base64-encoded-port>",
      "envvar:USER": "<base64-encoded-user>",
      "envvar:PASS": "<base64-encoded-pass>",
      "envvar:DB":   "<base64-encoded-dbname>"
    }
  }'