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

# The auth preflight

> Credentials are resolved per run: an API key in OCTOLENS_API_KEY, or a profile stored by octolens login.

Credentials are resolved per run: an API key in `OCTOLENS_API_KEY`, or a profile stored by `octolens login`. The no-usable-credential family — `MISSING_API_KEY`, `NOT_LOGGED_IN`, `NO_CREDENTIALS`, `NO_PROFILES` — all exit 3: test MEMBERSHIP of the family (or `exitCode === 3`) to decide "do I need to authenticate?", then read the specific member for the remedy. Which member a run gets depends on the command (`whoami` answers `NOT_LOGGED_IN` where a data command answers `NO_CREDENTIALS` for the identical state), so never branch on a single member. `CONFLICTING_CREDENTIALS`, `INVALID_API_KEY`, `MISSING_PROFILE`, `NO_STORED_PROFILE`, `UNAUTHORIZED` are deliberately NOT in the family — a credential exists and something else is wrong with it, so a login loop is the wrong recovery.

The membership test, as a shell function:

```sh theme={null}
needs_credentials() { [ "$1" -eq 3 ]; }   # test the family exit, never one member's code

octolens whoami --json
if needs_credentials $?; then
  octolens login   # get a credential, then re-run the original command
fi
```