Pre-requisites

  • Self-host your Hoop Gateway. Our managed instance does not support this feature.

Setup

  • The org-id is a value that you obtain in the user info endpoint. Use the command line to obtain this information, e.g.: hoop admin get userinfo -o json
  • The <random-string> is a secure key string that is going to be used to authenticated your requests

Make sure to use a tool with enough entropy to generate the <random-string> value. We recommend using openssl which is present in most unix systems by default. e.g.: openssl rand 64 | base64

Use the environment variable API_KEY=<org-id>|<random-string> when deploying your gateway. Example:

API_KEY='d9fe7aa1-b0a2-48d9-bde1-4ee759481b61|Vu0nc2nUwv8aCRhfOGspC84nUkDOvF0='

The organization ID is only available after you deploy the gateway. You’ll need to obtain this ID and then redeploy the instance with the API_KEY attribute set.

How it works

When requesting one of the allowed endpoints, you can pass the API Key in the Api-Key header with the configured value. The Gateway will validate the API Key and allow the request to proceed without the need for user authentication.

Permissions

The API Key has admin access in the system, make sure to keep the key secure.

Security Considerations

This method of accessing the API uses a static key with adminstrator privileges. The key NEVER expires and could only be revoked by redeploying the gateway. Make sure to keep this key secure and under a safe environment.