> ## 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

> Create, rotate, and revoke API keys for headless access to the Hoop Gateway

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.

<Warning>
  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.
</Warning>

## 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

<Steps>
  <Step title="Open the API Keys page">
    In the Web App sidebar, go to **Settings → API Keys** and click **Create new API key**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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 resource roles the key should reach.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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.

<Tabs>
  <Tab title="hoop login">
    Use `--api-key` to skip the browser-based login flow:

    ```sh theme={"dark"}
    hoop login --api-key hpk_your_key_value
    ```

    The key is written to `$HOME/.hoop/config.toml` and used for all subsequent CLI invocations.
  </Tab>

  <Tab title="hoop config create">
    On a fresh machine, set the Gateway URLs and the API key in one command:

    ```sh theme={"dark"}
    hoop config create \
        --api-key hpk_your_key_value \
        --api-url https://yourgateway-domain.tld \
        --grpc-url grpcs://yourgateway-domain.tld:8443
    ```

    The CLI rejects any value that does not start with `hpk_`.
  </Tab>
</Tabs>

After configuring, `hoop exec` and admin subcommands run under the key's identity:

```sh theme={"dark"}
hoop exec postgres-demo -i "SELECT * FROM customers"
```

### REST API authentication

Pass the key as a bearer token in the `Authorization` header:

```sh theme={"dark"}
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 resource roles and resources.

Keep the blast radius small. If automation only needs one query against one resource role, scope the key to a group limited to that resource role rather than using `admin`.

## Security Considerations

<Warning>
  Treat every `hpk_…` value as a production secret. Anyone with the raw key can call the Gateway as that identity until it is deactivated.
</Warning>

* **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.

<Note>
  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.
</Note>

To configure the legacy static key, set `API_KEY=<org-id>|<random-string>` on the Gateway:

```sh theme={"dark"}
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`.

<Warning>
  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.
</Warning>