API authentication

The X-Api-Key header, key issuance, idempotency, and the public mode used by HEVN REST calls.

All authenticated endpoints take one HEVN app API key (hvn_...), sent in the X-Api-Key header. There is no alternate header mode: Authorization: Bearer is reserved for the app’s own JWT session flow and is not used by API keys or the CLI.

API key mode

X-Api-Key: hvn_...
Accept: application/json
device-id: hevn-cli
device-type: cli
device-name: HEVN CLI

The CLI builds these headers from HEVN_API_KEY or saved login config:

export HEVN_API_KEY="hvn_..."

Use browser login:

hevn login

or direct API-key login for automation:

hevn login --api-key hvn_...
hevn login --api-key hvn_... --api-base-url https://api.example.com/api/v1

hevn login stores the API key (and the base URL, when provided or returned by the login callback) in the local CLI config.

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>

hevn transfer email and hevn transfer contact generate an idempotency key automatically when you don’t pass one; for hevn transfer --invoice-id, pass --idempotency-key explicitly if you need retry safety.

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.