Create Connection

curl --request POST \
  --url https://use.hoop.dev/api/connections \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_mode_connect": "enabled",
  "access_mode_exec": "enabled",
  "access_mode_runbooks": "enabled",
  "access_schema": "enabled",
  "agent_id": "1837453e-01fc-46f3-9e4c-dcf22d395393",
  "name": "pgdemo",
  "type": "database",
  "command": [
    "/bin/bash"
  ],
  "connection_tags": {
    "environment": "prod",
    "tier": "frontend"
  },
  "default_database": "<string>",
  "guardrail_rules": [
    "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
    "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
  ],
  "jira_issue_template_id": "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD",
  "redact_enabled": true,
  "redact_types": [
    "EMAIL_ADDRESS"
  ],
  "resource_name": "pgdemo",
  "reviewers": [
    "dba-group"
  ],
  "secret": {},
  "subtype": "postgres",
  "tags": [
    "prod"
  ]
}
'

{
  "access_mode_connect": "enabled",
  "access_mode_exec": "enabled",
  "access_mode_runbooks": "enabled",
  "access_schema": "enabled",
  "agent_id": "1837453e-01fc-46f3-9e4c-dcf22d395393",
  "name": "pgdemo",
  "type": "database",
  "command": [
    "/bin/bash"
  ],
  "connection_tags": {
    "environment": "prod",
    "tier": "frontend"
  },
  "default_database": "<string>",
  "guardrail_rules": [
    "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
    "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
  ],
  "id": "5364ec99-653b-41ba-8165-67236e894990",
  "jira_issue_template_id": "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD",
  "managed_by": "",
  "redact_enabled": true,
  "redact_types": [
    "EMAIL_ADDRESS"
  ],
  "resource_name": "pgdemo",
  "reviewers": [
    "dba-group"
  ],
  "secret": {},
  "status": "online",
  "subtype": "postgres",
  "tags": [
    "prod"
  ]
}

Connections

Create Connection

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

{
    "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

POST

connections

Create Connection

curl --request POST \
  --url https://use.hoop.dev/api/connections \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_mode_connect": "enabled",
  "access_mode_exec": "enabled",
  "access_mode_runbooks": "enabled",
  "access_schema": "enabled",
  "agent_id": "1837453e-01fc-46f3-9e4c-dcf22d395393",
  "name": "pgdemo",
  "type": "database",
  "command": [
    "/bin/bash"
  ],
  "connection_tags": {
    "environment": "prod",
    "tier": "frontend"
  },
  "default_database": "<string>",
  "guardrail_rules": [
    "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
    "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
  ],
  "jira_issue_template_id": "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD",
  "redact_enabled": true,
  "redact_types": [
    "EMAIL_ADDRESS"
  ],
  "resource_name": "pgdemo",
  "reviewers": [
    "dba-group"
  ],
  "secret": {},
  "subtype": "postgres",
  "tags": [
    "prod"
  ]
}
'

{
  "access_mode_connect": "enabled",
  "access_mode_exec": "enabled",
  "access_mode_runbooks": "enabled",
  "access_schema": "enabled",
  "agent_id": "1837453e-01fc-46f3-9e4c-dcf22d395393",
  "name": "pgdemo",
  "type": "database",
  "command": [
    "/bin/bash"
  ],
  "connection_tags": {
    "environment": "prod",
    "tier": "frontend"
  },
  "default_database": "<string>",
  "guardrail_rules": [
    "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
    "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
  ],
  "id": "5364ec99-653b-41ba-8165-67236e894990",
  "jira_issue_template_id": "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD",
  "managed_by": "",
  "redact_enabled": true,
  "redact_types": [
    "EMAIL_ADDRESS"
  ],
  "resource_name": "pgdemo",
  "reviewers": [
    "dba-group"
  ],
  "secret": {},
  "status": "online",
  "subtype": "postgres",
  "tags": [
    "prod"
  ]
}

Body

application/json

The request body resource

access_mode_connect

enum<string>

required

Toggle Port Forwarding

enabled - Enable to perform port forwarding for this connection
disabled - Disable port forwarding for this connection

Available options:

enabled,

disabled

access_mode_exec

enum<string>

required

Toggle Ad Hoc Executions

enabled - Enable to run ad-hoc executions for this connection
disabled - Disable ad-hoc executions for this connection

Available options:

enabled,

disabled

access_mode_runbooks

enum<string>

required

Toggle Ad Hoc Runbooks Executions

enabled - Enable to run runbooks for this connection
disabled - Disable runbooks execution for this connection

Available options:

enabled,

disabled

access_schema

enum<string>

required

Toggle Introspection Schema

enabled - Enable the instrospection schema in the webapp
disabled - Disable the instrospection schema in the webapp

Available options:

enabled,

disabled

agent_id

string<uuid>

required

The agent associated with this connection

Example:

"1837453e-01fc-46f3-9e4c-dcf22d395393"

name

string

required

Name of the connection. This attribute is immutable when updating it

Example:

"pgdemo"

type

enum<string>

required

Type represents the main type of the connection:

database - Database protocols
application - Custom applications
custom - Shell applications

Available options:

database,

application,

custom

Example:

"database"

command

string[]

Is the shell command that is going to be executed when interacting with this connection. This value is required if the connection is going to be used from the Webapp.

Example:

["/bin/bash"]

connection_tags

object

Tags to identify the connection

keys must contain between 1 and 64 alphanumeric characters, it may include (-), (_), (/), or (.) characters and it must not end with (-), (/) or (-).
values must contain between 1 and 256 alphanumeric characters, it may include space, (-), (_), (/), (+), (@), (:), (=) or (.) characters.

Show child attributes

Example:

{ "environment": "prod", "tier": "frontend" }

default_database

string

Default databases returns the configured value of the attribute secrets->'DB'

guardrail_rules

string[]

The guard rail association id rules

Example:

[
  "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
  "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
]

jira_issue_template_id

string

The jira issue templates ids associated to the connection

Example:

"B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"

redact_enabled

boolean

When this option is enabled it will allow managing the redact types through the attribute redact_types

redact_types

string[]

Redact Types is a list of info types that will used to redact the output of the connection. Possible values are described in the DLP documentation: https://cloud.google.com/sensitive-data-protection/docs/infotypes-reference

Example:

["EMAIL_ADDRESS"]

resource_name

string

Resource to which this connection belongs to, it'll be created if it doesn't exist

Example:

"pgdemo"

reviewers

string[]

Reviewers is a list of groups that will review the connection before the user could execute it

Example:

["dba-group"]

secret

object

Secrets are environment variables that are going to be exposed in the runtime of the connection:

{ envvar:[env-key]: [base64-val] } - Expose the value as environment variable
{ filesystem:[env-key]: [base64-val] } - Expose the value as a temporary file path creating the value in the filesystem

The value could also represent an integration with a external provider:

{ envvar:[env-key]: _aws:[secret-name]:[secret-key] } - Obtain the value dynamically in the AWS secrets manager and expose as environment variable
{ envvar:[env-key]: _envjson:[json-env-name]:[json-env-key] } - Obtain the value dynamically from a JSON env in the agent runtime. Example: MYENV={"KEY": "val"}

Show child attributes

subtype

string

Sub Type is the underline implementation of the connection:

postgres - Implements Postgres protocol
mysql - Implements MySQL protocol
mongodb - Implements MongoDB Wire Protocol
mssql - Implements Microsoft SQL Server Protocol
oracledb - Implements Oracle Database Protocol
tcp - Forwards a TCP connection
ssh - Forwards a SSH connection
httpproxy - Forwards a HTTP connection
dynamodb - AWS DynamoDB experimental integration
cloudwatch - AWS CloudWatch experimental integration

Example:

"postgres"

Response

Created

access_mode_connect

enum<string>

required

Toggle Port Forwarding

enabled - Enable to perform port forwarding for this connection
disabled - Disable port forwarding for this connection

Available options:

enabled,

disabled

access_mode_exec

enum<string>

required

Toggle Ad Hoc Executions

enabled - Enable to run ad-hoc executions for this connection
disabled - Disable ad-hoc executions for this connection

Available options:

enabled,

disabled

access_mode_runbooks

enum<string>

required

Toggle Ad Hoc Runbooks Executions

enabled - Enable to run runbooks for this connection
disabled - Disable runbooks execution for this connection

Available options:

enabled,

disabled

access_schema

enum<string>

required

Toggle Introspection Schema

enabled - Enable the instrospection schema in the webapp
disabled - Disable the instrospection schema in the webapp

Available options:

enabled,

disabled

agent_id

string<uuid>

required

The agent associated with this connection

Example:

"1837453e-01fc-46f3-9e4c-dcf22d395393"

name

string

required

Name of the connection. This attribute is immutable when updating it

Example:

"pgdemo"

type

enum<string>

required

Type represents the main type of the connection:

database - Database protocols
application - Custom applications
custom - Shell applications

Available options:

database,

application,

custom

Example:

"database"

command

string[]

Is the shell command that is going to be executed when interacting with this connection. This value is required if the connection is going to be used from the Webapp.

Example:

["/bin/bash"]

connection_tags

object

Tags to identify the connection

keys must contain between 1 and 64 alphanumeric characters, it may include (-), (_), (/), or (.) characters and it must not end with (-), (/) or (-).
values must contain between 1 and 256 alphanumeric characters, it may include space, (-), (_), (/), (+), (@), (:), (=) or (.) characters.

Show child attributes

Example:

{ "environment": "prod", "tier": "frontend" }

default_database

string

Default databases returns the configured value of the attribute secrets->'DB'

guardrail_rules

string[]

The guard rail association id rules

Example:

[
  "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
  "B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"
]

string<uuid>

Unique ID of the resource

Example:

"5364ec99-653b-41ba-8165-67236e894990"

jira_issue_template_id

string

The jira issue templates ids associated to the connection

Example:

"B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD"

managed_by

string

Managed By is a read only field that indicates who is managing this resource. When this attribute is set, this resource is considered immutable

Example:

""

redact_enabled

boolean

When this option is enabled it will allow managing the redact types through the attribute redact_types

redact_types

string[]

Example:

["EMAIL_ADDRESS"]

resource_name

string

Resource to which this connection belongs to, it'll be created if it doesn't exist

Example:

"pgdemo"

reviewers

string[]

Reviewers is a list of groups that will review the connection before the user could execute it

Example:

["dba-group"]

secret

object

Secrets are environment variables that are going to be exposed in the runtime of the connection:

{ envvar:[env-key]: [base64-val] } - Expose the value as environment variable
{ filesystem:[env-key]: [base64-val] } - Expose the value as a temporary file path creating the value in the filesystem

The value could also represent an integration with a external provider:

{ envvar:[env-key]: _aws:[secret-name]:[secret-key] } - Obtain the value dynamically in the AWS secrets manager and expose as environment variable
{ envvar:[env-key]: _envjson:[json-env-name]:[json-env-key] } - Obtain the value dynamically from a JSON env in the agent runtime. Example: MYENV={"KEY": "val"}

Show child attributes

status

enum<string>

Status is a read only field that informs if the connection is available for interaction

online - The agent is connected and alive
offline - The agent is not connected

Available options:

online,

offline

subtype

string

Sub Type is the underline implementation of the connection:

postgres - Implements Postgres protocol
mysql - Implements MySQL protocol
mongodb - Implements MongoDB Wire Protocol
mssql - Implements Microsoft SQL Server Protocol
oracledb - Implements Oracle Database Protocol
tcp - Forwards a TCP connection
ssh - Forwards a SSH connection
httpproxy - Forwards a HTTP connection
dynamodb - AWS DynamoDB experimental integration
cloudwatch - AWS CloudWatch experimental integration

Example:

"postgres"

Agents

Authentication

Connections

Data Masking Rules

AWS

Features

Guard Rails

Server Management

Jira

Organization Management

Plugins

Runbooks

Proxy Manager

Reports

Resources

Reviews

Search

User Management

Sessions

Create Connection

Types of Connections

Tags

Body

Response