Skip to main content
An API key is the credential the CLI, the SDKs, and the API 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_.
For your own interactive use, prefer hiloop login: 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.

​
Mint a key

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:
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:
The SDKs and the raw API still read the key from HILOOP_API_KEY; the stored copy is a CLI convenience.

​
List keys

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

​
Revoke a key

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.