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

# 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:

```http theme={null}
Authorization: Bearer hvn_...
Accept: application/json
device-id: hevn-cli
device-type: cli
device-name: HEVN CLI
```

Set it manually:

```bash theme={null}
export HEVN_API_KEY="hvn_..."
# Optional. Defaults to Authorization.
export HEVN_API_KEY_HEADER="Authorization"
```

Use browser login:

```bash theme={null}
hevn login
```

or direct API-key login for automation:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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:

```http theme={null}
Idempotency-Key: <stable-operation-id>
```

CLI example:

```bash theme={null}
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:

```bash theme={null}
hevn whoami --yaml
```

## Public mode

`PublicApi` sends only:

```http theme={null}
Accept: application/json
```

It is used for FX rates and public invoice lookup.

<Warning>
  Debug output may include authentication headers. Redact debug logs before sharing them.
</Warning>