Authentication

Authentication modes and headers used by HEVN CLI REST calls.

The CLI uses one HEVN API key for authenticated app and transfer endpoints, plus a public mode for unauthenticated reads.

HEVN API key mode

Authenticated endpoints build headers from HEVN_API_KEY or saved login config.

Default header:

Authorization: Bearer hvn_...
Accept: application/json
device-id: hevn-cli
device-type: cli
device-name: HEVN CLI

Set it manually:

export HEVN_API_KEY="hvn_..."
# Optional. Defaults to Authorization.
export HEVN_API_KEY_HEADER="Authorization"

Use browser login:

hevn login

or direct API-key login for automation:

hevn login --api-key hvn_...
hevn login --api-key hvn_... --api-key-header X-Api-Key

hevn login stores the API key, header mode, and optional base URL in the local CLI config.

Alternate X-Api-Key mode

Some deployments require X-Api-Key instead of Authorization:

export HEVN_API_KEY="hvn_..."
export HEVN_API_KEY_HEADER="X-Api-Key"

The CLI reuses whichever header was configured for all authenticated endpoints, including transfers.

Non-interactive auth

In CI and other non-interactive environments, avoid browser login and pass a key directly:

hevn login --api-key hvn_...
HEVN_API_KEY=hvn_... hevn whoami --yaml

If interactive login is attempted in non-interactive mode, the CLI exits with AUTH_REQUIRED and reports the supported auth methods.

Idempotency

Transfer and deposit writes can include:

Idempotency-Key: <stable-operation-id>

CLI example:

hevn transfer contact \
  --contact-id <contact-id> \
  --amount 25 \
  --idempotency-key <stable-operation-id>

API-key introspection

Use whoami to inspect the active API key, owning app, scopes, balance, and remaining spend limit:

hevn whoami --yaml

Public mode

PublicApi sends only:

Accept: application/json

It is used for FX rates and public invoice lookup.

Debug output may include authentication headers. Redact debug logs before sharing them.