API keys

API keys are long-lived bearer tokens for programmatic REST access — automation, integrations, and scripts that call the HeliosLogs API. Manage them under Admin → API keys.

API keys vs. ingest tokens

API keys authenticate REST calls (search, aggregate, admin) through the same path as a user session. Ingest tokens are for pushing logs and are scoped to an env/index. Use the right one for the job.

Creating a key

Specify:

• Name — a label.
• Scope — admin (full admin REST access) or standard (non-admin, subject to the same RBAC allowlist model as a normal user).
• Expiry — an optional lifetime in days; omit for a key that never expires.

The secret is shown once at creation (it's prefixed hlk_); copy it then. Listings afterward show only the last four characters.

Using a key

curl -H "Authorization: Bearer hlk_<secret>" \
  'https://helios.example.com/api/search?q=level:error&env=prod'

A key authenticates as a synthesized admin or standard principal — a standard key sees only what its access allows, exactly like a scoped user.

Lifecycle

• Disable/enable a key without deleting it.
• Delete to revoke immediately.
• Expired keys are rejected automatically.
• Each key records who created it and when it was last used (for audit).

Least privilege

Prefer standard keys scoped to what the integration needs; reserve admin keys for genuine administrative automation, set an expiry, and rotate them. See Security hardening.