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

# Authentication

> Configure API credentials for the Nullspace CLI.

The CLI authenticates with the same API key used by the Python SDK and HTTP
API. Hosted private beta and self-hosted single-host appliances both use bearer
API keys; only the API base URL differs.

## Environment Variables

For scripts, CI, and coding agents, prefer environment variables:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
```

The CLI also accepts `NULLSPACE_BASE_URL` as a base-url alias.
Use `NULLSPACE_API_URL` for SDK/CLI clients; `VITE_NULLSPACE_API_BASE` is a
console build-time variable.

For the self-hosted single-host appliance in localhost/no-domain mode:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY="$(sudo cat /etc/nullspace/operator-api-key)"
export NULLSPACE_API_URL=http://localhost
```

For owned-domain mode:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_URL=https://nullspace.example
```

## Login Command

For local interactive use, save an API key and endpoint with:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace auth login --api-url https://api.13-215-85-171.sslip.io
```

The command prompts for the key and writes it to
`~/.nullspace/config.json`. Environment variables still take precedence, so you
can override the saved key or API URL per shell or per project.

If you only need to update the saved key and keep the current API URL, run:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace auth login
```

## Project `.env`

When a project needs its own endpoint or key, put a `.env` file in the current
working directory:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
NULLSPACE_API_KEY=ns_live_...
NULLSPACE_API_URL=https://api.your-nullspace-domain
```

Never commit `.env` files that contain real credentials.

## Config Precedence

Credential lookup order is:

1. Explicit SDK arguments when you are using Python directly.
2. `NULLSPACE_API_KEY`, `NULLSPACE_API_URL`, and `NULLSPACE_BASE_URL`.
3. A project `.env` in the current working directory.
4. `~/.config/nullspace/config.json`.
5. `~/.nullspace/config.json`.

Hosted private-beta and self-hosted appliance commands require an API key. If
no base URL is configured, the SDK defaults to `http://localhost:3000`, which
is intended for local development direct API access. The appliance quickstart
uses `http://localhost` through Caddy.

To see which source won without printing any secrets, run:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace auth status
```

It prints the resolved API URL, the winning key source (`env`, `.env`,
`xdg-config`, `legacy-config`, or `none`), and a `sha256:` key fingerprint —
never the key itself. Add `--json` for machine-readable output, including
every source consulted. If the legacy `~/.nullspace/config.json` exists, the
command prints a one-line pointer to the blessed
`~/.config/nullspace/config.json` location.

## Verify Access

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace doctor
nullspace quickstart
nullspace machine list --json
```

For raw HTTP verification:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
curl -fsS \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  "${NULLSPACE_API_URL}/v1/machines"
```

## Related

* [API Keys](../guides/api-keys)
* [SDK Config](../reference/config)
* [Environment Variables](../reference/env-vars)
* [Self-Hosted Single-Host](../quickstarts/self-hosted-single-host)