Skip to main content

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

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: 
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: 
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: 
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: 
landbase-cli auth status
If it says “no key found”, set it explicitly: 
landbase-cli auth login --key
Or export it as an environment variable: 
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: 
landbase-cli auth status
To force legacy mode (direct AgentOS, API key only): 
export LANDBASE_LEGACY_MODE=1
landbase-cli auth status
To go back to platform mode, unset the variable: 
unset LANDBASE_LEGACY_MODE
See Platform mode vs. legacy mode for more background.

​
Clear stored credentials and start fresh

If you are unsure what state your credentials are in, clear everything and re-authenticate: 
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: 
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 with the verbose output (redact your API key before sharing).