Skip to main content
POST
Create Connection

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"

​
access_max_duration
integer

Maximum duration in seconds for JIT access sessions on this connection

Example:

3600

​
attributes
string[]

Attributes associated with this connection. Includes Hoop-managed attributes (e.g. the active protection profile attribute); omitting a managed name on update detaches the connection from it.

Example:
​
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:
​
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.
Example:
​
default_database
string

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

​
force_approve_groups
string[]

Groups that can force approve requests for this connection

Example:
​
guardrail_rules
string[]

The guard rail association id rules

Example:
​
jira_issue_template_id
string

The jira issue templates ids associated to the connection

Example:

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

​
jit_access_duration_sec
integer

JitAccessDurationSec is the fixed access duration in seconds enforced by a JIT access request rule. When set, the user cannot choose a custom duration and must request access for this exact window.

Example:

1800

​
mandatory_metadata_fields
string[]

MandatoryMetadataFields are fields that must be present in the metadata for this connection for every session.

Example:
​
mcp_oauth_flow_id
string

MCPOAuthFlowID adopts a completed MCP OAuth login into a durable grant for this connection. Write-only, and only meaningful for the "mcpproxy" subtype.

The login runs before the connection exists, so the token it obtained is keyed by the flow rather than by connection. Passing the flow id here at save time joins the two: the gateway stores the refresh token against this connection and renews the access token at every session open, instead of relying on the frozen HEADER_AUTHORIZATION value alone, which stops working when the provider's token expires.

Write-only is enforced by ToOpenApi, which never populates this field — not by a struct tag. swag reads readonly and has no writeonly counterpart (field_parser.go only consults readOnlyTag), so the tag that used to sit here was inert and the published spec advertised the field as readable. The omitempty keeps it out of every response body.

Example:

"7c8a1234-5678-9abc-def0-123456789abc"

​
min_review_approvals
integer

Minimum number of approvals required to execute this connection

Example:

2

​
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:
​
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 must approve access to the connection before the user can execute it

Example:
​
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"}
​
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"

​
tags
string[]

DEPRECATED: Tags to classify the connection

Example:

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"

​
access_max_duration
integer

Maximum duration in seconds for JIT access sessions on this connection

Example:

3600

​
attributes
string[]

Attributes associated with this connection. Includes Hoop-managed attributes (e.g. the active protection profile attribute); omitting a managed name on update detaches the connection from it.

Example:
​
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:
​
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.
Example:
​
default_database
string

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

​
effective_features
object

EffectiveFeatures reports which features will actually act on this connection, resolving attribute-based associations as well as direct ones.

Null means "unknown", never "nothing is active" — the two must not be confused by a caller deciding whether to warn a user. It is null on the list endpoint, which does not resolve it, and on the detail endpoint when resolution failed (the gateway logs the failure).

Deliberately not omitempty: an absent key and an explicit null are different contracts, and the one documented here is null.

​
force_approve_groups
string[]

Groups that can force approve requests for this connection

Example:
​
guardrail_rules
string[]

The guard rail association id rules

Example:
​
id
string<uuid>
read-only

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"

​
jit_access_duration_sec
integer

JitAccessDurationSec is the fixed access duration in seconds enforced by a JIT access request rule. When set, the user cannot choose a custom duration and must request access for this exact window.

Example:

1800

​
managed_attributes
string[]
read-only

Hoop-managed attributes associated with this connection (e.g. the active protection profile attribute). Computed on reads; manage the association through the attributes field.

Example:
​
managed_by
string
read-only

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:

""

​
mandatory_metadata_fields
string[]

MandatoryMetadataFields are fields that must be present in the metadata for this connection for every session.

Example:
​
mcp_oauth_flow_id
string

MCPOAuthFlowID adopts a completed MCP OAuth login into a durable grant for this connection. Write-only, and only meaningful for the "mcpproxy" subtype.

The login runs before the connection exists, so the token it obtained is keyed by the flow rather than by connection. Passing the flow id here at save time joins the two: the gateway stores the refresh token against this connection and renews the access token at every session open, instead of relying on the frozen HEADER_AUTHORIZATION value alone, which stops working when the provider's token expires.

Write-only is enforced by ToOpenApi, which never populates this field — not by a struct tag. swag reads readonly and has no writeonly counterpart (field_parser.go only consults readOnlyTag), so the tag that used to sit here was inert and the published spec advertised the field as readable. The omitempty keeps it out of every response body.

Example:

"7c8a1234-5678-9abc-def0-123456789abc"

​
mcp_oauth_granted
boolean
read-only

MCPOAuthGranted reports that a durable MCP OAuth grant exists for this connection, so its credential is renewed from a refresh token at every session open rather than frozen at the value it was authorized with.

The edit screen cannot infer this from the env vars. A brokered OAuth login and a pasted token both end up as one HEADER_AUTHORIZATION, and MCP_AUTH collapses "oauth" to "static" because that is all the agent needs to know (see services.MCPOAuthGrantSubType). Without this field the form has to guess which mode the admin chose, guesses "static", and an OAuth connection reopens offering to replace a token it should be offering to re-authorize.

Presence only — no token, no expiry, nothing the grant holds.

Example:

true

​
mcp_oauth_warning
string
read-only

MCPOAuthWarning reports that the connection was saved but the MCP OAuth login named by mcp_oauth_flow_id was not attached to it. Present only on the create/update response that produced it.

The save succeeded and the connection still works on its frozen HEADER_AUTHORIZATION, so this is not an error status. What it is not is silent: without a grant the credential is never renewed, the connection stops working the moment the provider expires that token, and the admin needs to hear it at save time rather than from a failing session days later.

Example:

"the oauth login authorized https://a.example/mcp but the connection points at https://b.example/mcp"

​
min_review_approvals
integer

Minimum number of approvals required to execute this connection

Example:

2

​
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:
​
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 must approve access to the connection before the user can execute it

Example:
​
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"}
​
secrets_updated_at
string
read-only

SecretsUpdatedAt is the timestamp of the last replacement of any inline secret value for this connection. Null when no inline secret has been modified since the write-only secrets feature was introduced. References to external providers (AWS Secrets Manager, Vault, IAM RDS) do not affect this field.

Example:

"2025-01-15T10:30:00Z"

​
status
enum<string>
read-only

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"

​
tags
string[]

DEPRECATED: Tags to classify the connection

Example: