Skip to main content

​
Prerequisites

To get the most out of this guide, you will need to:

​
Installation

Through homebrew:
  brew tap hoophq/brew https://github.com/hoophq/brew.git
  brew install hoop
To upgrade it:
  brew update && brew upgrade hoop

​
Authentication

The authentication process requires either an access token or an API key to interact with the gateway. The following sections outline the various authentication scenarios when using the command line interface.
The authentication process requires knowning the gateway instance URL where the Hoop gateway is running. Our managed instances are hosted under the URL:
https://use.hoop.dev
Contact your administrator if you have a self hosted installation and don’t know this information.

​
Connection Usage Scenario

This authentication method is recommended for users who need to regularly access and manage resources within their permission scope. Users will authenticate to obtain a valid access token, which remains active based on your identity provider’s expiration policy.
This command should be executed only once in your machine. It creates and wipes the file $HOME/.hoop/config.toml in your local machine
hoop config create --api-url https://yourgateway-domain.tld
This command must be executed every time the token expires or the command above is executed.
hoop login

​
Automation Usage Scenario

​
Programmatic API Access

This authentication method is designed for administrators who need programmatic access to the API for tasks such as managing connections, configuring policies, or executing operations within automation pipelines. Programmatic access requires static authentication credentials that can be obtained through the following methods:

​
Static API Key

A Static API Key provides persistent authentication by setting an environment variable in the gateway with a secure random string. Configure the token in your local configuration using this command: 
HOOP_TOKEN=<api-key> hoop config create --api-url https://yourgateway-domain.tld

​
Service Account

Service Account authentication is available if your identity provider supports the OAuth2 Client Credentials Grant type. 
export HOOP_TOKEN="$(/tmp/issue-client-credentials-token-from-idp.sh)"
hoop config create --api-url https://yourgateway-domain.tld
Access tokens obtained from your identity provider typically have an expiration period. To maintain continuous access, create a script that can generate fresh access tokens as needed.

​
Using Environment Variables

Another way to use the command line is by exporting the following environment variables: 
export HOOP_APIURL=https://use.hoop.dev
export HOOP_GRPCURL=grpcs://use.hoop.dev:8443
export HOOP_TOKEN=<your-access-token-or-api-key>
export HOOP_TLSCA=file:///path/to/ca.pem
# test it
hoop admin get userinfo
When using environment variables, it will ignore the local configuration file $HOME/.hoop/config.yaml

​
Managing Configuration

  • Configure your Gateway URL and clear any existent configuration
hoop config create --api-url https://yourgateway-domain.tld
  • Configure the Gateway URL and the gRPC URL
hoop config create
  --api-url https://yourgateway-domain.tld \
  --grpc-url grpcs://yourgateway-domain.tld:443
This flag is optional and used only to interact with connections. The --grpc-url is obtained automatically from the Api when a user Sign In (issue the hoop login command)
  • Configure the Gateway URL, the gRPC URL and the TLS Certificate Root Certificate
hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca=file:///tmp/ca.pem

# inline configuration
hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca="base64://$(cat /tmp/ca.pem |base64)"
This option should be used if your gateway is running with self signed certificates.
  • Show API_URL, GRPC_URL and TLS_CA configuration
hoop config view
  • Show all configuration with the access token (contains sensitive information)
hoop config view --raw
  • Show sections of configuration
hoop config view api_url
hoop config view grpc_url
hoop config view token
hoop config view tls_ca
  • Wipe Local Configuration
hoop config clear