Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

API Keys authenticate to the Hoop Gateway without an interactive browser login. Each key is a random string prefixed with hpk_ that works as a bearer token for both the REST API and the CLI. Unlike the legacy static API_KEY environment variable, managed keys are:
  • Managed at runtime from the Web App, with no redeploy to create or revoke.
  • Group-scoped: the key inherits the permissions of its assigned groups.
  • Individually revocable: deactivate one key without touching any other.
  • Auditable: the Gateway tracks who created each key, who deactivated it, and when it was last used.
The raw key value is shown only once, at creation time. The Gateway stores only a SHA-256 hash plus a masked preview (e.g. hpk_1nzb***************************************). If you lose the raw value, create a new key; it cannot be recovered.

​
Managing API Keys via Web App

API Keys are managed from Settings → API Keys in the Web App. This section is admin-only.

​
Create a new API key

1

Open the API Keys page

In the Web App sidebar, go to Settings → API Keys and click Create new API key.
2

Set a name

Give the key a descriptive, org-unique name (for example ai-agent-sre or payments-automation). The name identifies the key in the list and in audit logs.
3

Assign groups

Select one or more groups. The key’s permissions are the union of those groups. Use admin for admin-level access; otherwise assign the groups that own the connections the key should reach.
4

Save and copy the key

Click Save. The Gateway displays the full hpk_… value once. Copy it immediately into a secrets manager; once you navigate away, it is no longer retrievable.

​
Configure or rename an existing key

From the API Keys list, open the actions menu (⋯) and choose Configure to update the name or assigned groups. The raw key value does not change, so existing clients keep working.

​
Deactivate an API key

Deactivation is a soft delete: the key stops authenticating, but the record remains for audit with deactivated_by and deactivated_at populated. From the actions menu, choose Deactivate API key and confirm. In-flight requests using that key begin receiving 401 Unauthorized.

​
Reactivate a deactivated key

Choose Activate API key from the actions menu. Status flips back to active, deactivation metadata is cleared, and the original secret value is reused.

​
Using the API Key

Once you have an hpk_… value, use it anywhere the Gateway accepts an authenticated caller.

​
CLI authentication

Supply the key at login or when creating the local config file.
Use --api-key to skip the browser-based login flow:
hoop login --api-key hpk_your_key_value
The key is written to $HOME/.hoop/config.toml and used for all subsequent CLI invocations.
After configuring, hoop exec and admin subcommands run under the key’s identity: 
hoop exec postgres-demo -i "SELECT * FROM customers"

​
REST API authentication

Pass the key as a bearer token in the Authorization header: 
curl -X GET https://yourgateway-domain.tld/api/userinfo \
    -H "Authorization: Bearer hpk_your_key_value"
Any REST endpoint that accepts a user access token also accepts an hpk_ key, subject to the permissions of its assigned groups.

​
Permissions

An API key has exactly the permissions of its assigned groups:
  • A key in admin can perform any administrative action.
  • A key in a scoped group (for example engineering) can only reach that group’s connections and resources.
Keep the blast radius small. If automation only needs one query against one connection, scope the key to a group limited to that connection rather than using admin.

​
Security Considerations

Treat every hpk_… value as a production secret. Anyone with the raw key can call the Gateway as that identity until it is deactivated.
  • Store in a secrets manager. Never commit keys or paste them into chat tools. Inject the value at runtime from AWS Secrets Manager, Vault, Kubernetes Secrets, etc.
  • Rotate on a schedule. Deactivation is instant and non-destructive: create a new key, cut consumers over, then deactivate the old one without a deploy.
  • Rotate on suspected exposure. If a key may have leaked, deactivate it immediately. The change takes effect on the next request.
  • Audit trail. created_by, deactivated_by, and last_used_at answer “who issued this” and “is this still in use” without guessing.

​
Legacy Static API Key

Before managed API Keys, the Gateway supported a single static key configured at deploy time via the API_KEY environment variable. It remains accepted for backward compatibility.
New integrations should use managed API Keys. The legacy static key cannot be revoked without redeploying the Gateway, has no audit trail, and always runs with administrator privileges.
To configure the legacy static key, set API_KEY=<org-id>|<random-string> on the Gateway: 
API_KEY='d9fe7aa1-b0a2-48d9-bde1-4ee759481b61|Vu0nc2nUwv8aCRhfOGspC84nUkDOvF0='
  • <org-id> is the value returned by hoop admin get userinfo -o json.
  • <random-string> should come from a high-entropy source, e.g. openssl rand 64 | base64.
  • Callers pass the key in the Api-Key header rather than Authorization: Bearer.
The legacy static key has administrator privileges, never expires, and can only be revoked by redeploying the Gateway with a different API_KEY. Prefer managed API Keys for new work.