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

# How to troubleshoot authentication

> Diagnose and resolve common authentication failures — from expired sessions to missing API keys and platform mode mismatches.

# How to troubleshoot authentication

This guide walks through the most common authentication problems and how to resolve them.

***

## Start with the doctor command

The quickest first step is:

```bash theme={null}
landbase-cli doctor
```

This checks your installation, authentication status, and connectivity, and prints a summary of what is working and what is not. Fix the items it flags before going further.

***

## Check your current auth status

```bash theme={null}
landbase-cli auth status
```

This prints whether you are authenticated, the auth method (OAuth session or API key), and the account you are authenticated as. If it returns an error, you are not authenticated.

***

## You are not authenticated at all

Run the login flow:

```bash theme={null}
landbase-cli auth login
```

This opens a browser window for OAuth. Complete the login and return to the terminal. The CLI saves the session to `~/.landbase/platform.json`.

If you cannot open a browser (CI environment, remote server), use an API key instead:

```bash theme={null}
landbase-cli auth login --key
```

Paste your API key when prompted.

***

## Your session has expired

Platform OAuth sessions expire. If commands are returning auth errors after previously working, your session has expired. Re-run:

```bash theme={null}
landbase-cli auth login
```

This refreshes the session. You do not need to log out first.

***

## You have an API key but commands are failing with auth errors

Check that the key is correctly set:

```bash theme={null}
landbase-cli auth status
```

If it says "no key found", set it explicitly:

```bash theme={null}
landbase-cli auth login --key
```

Or export it as an environment variable:

```bash theme={null}
export LANDBASE_API_KEY=lbk_your_key_here
landbase-cli auth status
```

The environment variable takes precedence over the stored key.

***

## Wrong mode: platform vs. legacy

There are two auth modes. Most users are on **platform mode** (the default). If you are getting auth errors that reference `lbk_` keys when you have an `lbs_` session (or vice versa), you may have the wrong mode active.

Check which mode is active:

```bash theme={null}
landbase-cli auth status
```

To force legacy mode (direct AgentOS, API key only):

```bash theme={null}
export LANDBASE_LEGACY_MODE=1
landbase-cli auth status
```

To go back to platform mode, unset the variable:

```bash theme={null}
unset LANDBASE_LEGACY_MODE
```

See [Platform mode vs. legacy mode](/docs/explanation/platform-vs-legacy) for more background.

***

## Clear stored credentials and start fresh

If you are unsure what state your credentials are in, clear everything and re-authenticate:

```bash theme={null}
landbase-cli auth logout
landbase-cli auth login
```

`logout` removes the stored session from `~/.landbase/platform.json` and `~/.landbase/config.json`. After this, `auth status` should say "not authenticated" and `auth login` will walk you through a fresh login.

***

## Still failing after all of the above

Run with verbose output to see what is being sent and received:

```bash theme={null}
landbase-cli auth status --verbose
```

The verbose output shows the exact HTTP request and response headers, which can reveal whether the issue is a credentials problem, a connectivity problem, or an API error.

If you are still stuck, contact [Landbase support](https://support.landbase.com/landbase/directories) with the verbose output (redact your API key before sharing).

***

## Related

* [auth command reference](/docs/reference/auth) — full auth command options
* [Platform mode vs. legacy mode](/docs/explanation/platform-vs-legacy) — background on the two auth models
* [environment variables reference](/docs/reference/env-vars) — LANDBASE\_API\_KEY and related vars