> ## Documentation Index > Fetch the complete documentation index at: https://hoopdev-doc-container-images.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Gets a resource > Gets a resource by ID for the organization. ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json get /resources/{name} 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.133.1 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: Runbooks - name: Guard Rails - name: Reviews - 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: /resources/{name}: get: tags: - Resources summary: Gets a resource description: Gets a resource by ID for the organization. parameters: - description: The resource name in: path name: name required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.ResourceResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Bad Request '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.ResourceResponse: properties: agent_id: description: The agent associated with this resource example: 1837453e-01fc-46f3-9e4c-dcf22d395393 format: uuid type: string created_at: description: The time the resource was created example: '2024-07-25T15:56:35.317601Z' readOnly: true type: string env_vars: additionalProperties: type: string description: The resource environment variables type: object id: description: The resource ID example: 15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7 format: uuid readOnly: true type: string mcp_oauth_warnings: description: >- MCPOAuthWarnings reports the roles in this request whose mcp_oauth_flow_id was not adopted into a durable grant. Present only on the create response that produced them, and empty when every login attached. items: $ref: '#/components/schemas/openapi.MCPOAuthRoleWarning' readOnly: true type: array name: description: The resource name example: my-resource type: string roles: description: Connections (roles) associated with this resource items: $ref: '#/components/schemas/openapi.Connection' type: array subtype: description: The resource subtype example: mysql type: string type: description: The resource type example: database type: string updated_at: description: The time the resource was updated example: '2024-07-25T15:56:35.317601Z' readOnly: true type: string required: - agent_id type: object openapi.HTTPError: properties: message: example: the error description type: string type: object openapi.MCPOAuthRoleWarning: properties: name: description: Name of the role (connection) the login failed to attach to example: linear-mcp type: string warning: description: Warning is the reason the login was not attached example: >- the oauth login authorized https://a.example/mcp but the connection points at https://b.example/mcp type: string type: object openapi.Connection: properties: access_max_duration: description: >- Maximum duration in seconds for JIT access sessions on this connection example: 3600 type: integer access_mode_connect: description: |- Toggle Port Forwarding * enabled - Enable to perform port forwarding for this connection * disabled - Disable port forwarding for this connection enum: - enabled - disabled type: string access_mode_exec: description: |- Toggle Ad Hoc Executions * enabled - Enable to run ad-hoc executions for this connection * disabled - Disable ad-hoc executions for this connection enum: - enabled - disabled type: string access_mode_runbooks: description: |- Toggle Ad Hoc Runbooks Executions * enabled - Enable to run runbooks for this connection * disabled - Disable runbooks execution for this connection enum: - enabled - disabled type: string access_schema: description: |- Toggle Introspection Schema * enabled - Enable the instrospection schema in the webapp * disabled - Disable the instrospection schema in the webapp enum: - enabled - disabled type: string agent_id: description: The agent associated with this connection example: 1837453e-01fc-46f3-9e4c-dcf22d395393 format: uuid type: string attributes: description: >- 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: - production - pii items: type: string type: array command: description: >- 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 items: type: string type: array connection_tags: additionalProperties: type: string description: >- 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: environment: prod tier: frontend type: object default_database: description: >- Default databases returns the configured value of the attribute secrets->'DB' type: string effective_features: allOf: - $ref: '#/components/schemas/openapi.ConnectionEffectiveFeatures' description: >- 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. readOnly: true force_approve_groups: description: Groups that can force approve reviews for this connection example: - sre-team items: type: string type: array guardrail_rules: description: The guard rail association id rules example: - 5701046A-7B7A-4A78-ABB0-A24C95E6FE54 - B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD items: type: string type: array id: description: Unique ID of the resource example: 5364ec99-653b-41ba-8165-67236e894990 format: uuid readOnly: true type: string jira_issue_template_id: description: The jira issue templates ids associated to the connection example: B19BBA55-8646-4D94-A40A-C3AFE2F4BAFD type: string jit_access_duration_sec: description: >- 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 type: integer managed_attributes: description: |- 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: - hoop_protection_profile-soc2_type2 items: type: string readOnly: true type: array managed_by: description: >- 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: '' readOnly: true type: string mandatory_metadata_fields: description: >- MandatoryMetadataFields are fields that must be present in the metadata for this connection for every session. example: - environment - tier items: type: string type: array mcp_oauth_flow_id: description: >- 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 type: string mcp_oauth_granted: description: >- 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 readOnly: true type: boolean mcp_oauth_warning: description: >- 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 readOnly: true type: string min_review_approvals: description: >- Minimum number of review approvals required to execute this connection example: 2 type: integer name: description: Name of the connection. This attribute is immutable when updating it example: pgdemo type: string redact_enabled: description: >- When this option is enabled it will allow managing the redact types through the attribute `redact_types` type: boolean redact_types: description: >- 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 items: type: string type: array resource_name: description: >- Resource to which this connection belongs to, it'll be created if it doesn't exist example: pgdemo type: string reviewers: description: >- Reviewers is a list of groups that will review the connection before the user could execute it example: - dba-group items: type: string type: array secret: additionalProperties: {} description: >- 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"} type: object secrets_updated_at: description: >- 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' readOnly: true type: string status: description: >- 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 enum: - online - offline readOnly: true type: string subtype: description: |- 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 type: string tags: description: 'DEPRECATED: Tags to classify the connection' example: - prod items: type: string type: array type: description: |- Type represents the main type of the connection: * database - Database protocols * application - Custom applications * custom - Shell applications enum: - database - application - custom example: database type: string required: - access_mode_connect - access_mode_exec - access_mode_runbooks - access_schema - agent_id - name - type type: object openapi.ConnectionEffectiveFeatures: properties: access_request: allOf: - $ref: '#/components/schemas/openapi.ConnectionAccessRequestFeatures' description: AccessRequest reports approval coverage, split by access type. ai_session_analyzer: description: >- AISessionAnalyzer is true when an analyzer rule resolves for this connection. example: false type: boolean data_masking: description: >- DataMasking is true when any data masking rule resolves for this connection AND the gateway has an active masking provider. Note that redact_enabled on the connection is a legacy display field that no runtime code reads. example: true type: boolean guardrails: description: >- Guardrails is true when any guardrail rule resolves for this connection. example: true type: boolean jira_templates: description: >- JiraTemplates is true when the connection has a Jira issue template. Projection of jira_issue_template_id — no attribute-based path exists for it. example: false type: boolean mandatory_metadata: description: >- MandatoryMetadata is true when the connection requires metadata fields before a session starts. Projection of mandatory_metadata_fields — no attribute-based path exists for it. example: false type: boolean type: object openapi.ConnectionAccessRequestFeatures: properties: command: description: >- Command is true when an access request rule of type "command" resolves. example: true type: boolean jit: description: >- Jit is true when an access request rule of type "jit" resolves. The duration it enforces, when any, is reported by the connection's jit_access_duration_sec. example: false type: boolean legacy_reviewers: description: >- LegacyReviewers is true when the pre-rules review plugin has reviewer groups configured. It still applies on top of both access types. example: false type: boolean type: object ````