> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage API keys

> Mint, list, and revoke the API keys that authenticate the CLI, SDKs, and API.

An **API key** is the credential the [CLI](/reference/cli/hiloop), the [SDKs](/guides/using-the-sdks),
and the [API](/api-reference) use to authenticate. hiloop sends it as a bearer token; the edge
resolves it to your organization- and (for user keys) user-scoped identity. Keys are prefixed
`hil_`.

<Note>
  For your own interactive use, prefer [`hiloop login`](/guides/quickstart#authenticate-and-pick-a-project): it caches a
  short-lived, self-refreshing session instead of a static secret. Reach for
  an API key when you need a **static** credential: CI, automation, backend services, and the SDKs.
</Note>

## Mint a key

```sh theme={null}
hiloop keys create "ci pipeline"
```

The plaintext secret is shown **once** and never again — copy it immediately into your secret store.
hiloop only ever stores a hash, so a lost key can't be recovered, only revoked and replaced.

The name is how this key shows up everywhere — `hiloop whoami`, run listings, and audit
attribution — so pick one that identifies the consumer (a pipeline, a laptop, a service). Names are
unique among your live keys; revoking a key frees its name. Add `--description` to record what the
key is for.

Choose what the key acts as with `--kind`:

* `service_account` (default) — acts as the organization. Use this for CI, automation, and backend
  services.
* `user` — acts on behalf of you. The resolved identity includes your user id.

## Use it

Set it in the environment the CLI and SDKs read:

```sh theme={null}
export HILOOP_API_KEY="hil_…"
hiloop whoami
```

`hiloop whoami` confirms what the key resolves to — the principal (its kind, the user's email for
user keys, and the key's id and name) and the organization. It's the fastest way to check a key is valid
and scoped the way you expect.

On your own machine you can store the key instead of exporting it on every shell — the CLI then
picks it up like a login session. The credential lands in the macOS Keychain or Windows Credential
Manager where those are available, and otherwise (including Linux) in a private, owner-only
(`0600`) CLI config file:

```sh theme={null}
echo "hil_…" | hiloop login --with-key
```

The SDKs and the raw API still read the key from `HILOOP_API_KEY`; the stored copy is a CLI
convenience.

## List keys

```sh theme={null}
hiloop keys list
```

This lists your live keys — `NAME`, `KEY_ID`, `KIND`, and `CREATED` — never the secret. Revoked
keys drop out of the list.

## Revoke a key

```sh theme={null}
hiloop keys revoke <key-id-or-name>
```

Revocation is idempotent: revoking an already-revoked key succeeds, whether you pass the id or the
name. Revoke a key the moment it might be compromised, and rotate by minting a new one before
retiring the old.

## Good hygiene

* **Prefer `service_account` keys for automation**, scoped to the organization that needs them.
* **One key per consumer** (per CI pipeline, per service) so you can revoke one without disrupting
  the rest.
* **Never commit a key.** Keep it in your secret manager or CI secrets, and read it from
  `HILOOP_API_KEY` at runtime.