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

# Authentication

> How the CLI logs in and stores your API key

The CLI authenticates with the same workspace API keys as the `/v1` REST API. The fastest way to get set up is the browser-based login flow. No copy-pasting keys.

## Browser-based login (recommended)

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

Here's what happens:

<Steps>
  <Step title="The CLI opens your browser">
    A page on the GeoGen dashboard asks you to authorize the CLI. If you're not signed in, you'll be prompted to sign in first.
  </Step>

  <Step title="Pick a workspace">
    The dashboard shows a workspace picker. The CLI will only get access to the workspace you select.
  </Step>

  <Step title="Click Authorize">
    A new API key is minted with a label like `CLI: <your-device> (2026-05-22)` so you can identify and revoke it from **Settings → API Keys** later.
  </Step>

  <Step title="Done">
    The dashboard hands the key back to the CLI through a temporary local listener (bound to `127.0.0.1` only). The CLI writes it to `~/.geogen/config.json` and the browser shows "✓ GeoGen CLI authorized".
  </Step>
</Steps>

The flow times out after 5 minutes if you don't complete it.

### Login flags

| Flag                    | Description                                                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key <key>`       | Skip the browser flow and store this key directly (for scripts, CI, or when you already have a key).                                                              |
| `--device <name>`       | Override the device label used in the new key's name. Defaults to your machine's hostname.                                                                        |
| `--no-browser`          | Start the local listener and print the auth URL, but don't try to open a browser. Useful over SSH or in containers. Copy the URL to a browser on another machine. |
| `--base-url <url>`      | Override the API base URL (default: `https://api.geogen.io`).                                                                                                     |
| `--dashboard-url <url>` | Override the dashboard URL used for the consent page. By default it's derived from `--base-url`: `api.geogen.io` → `app.geogen.io`.                               |

### Examples

```bash theme={null}
# Default: browser flow
geogen login

# Scripts / CI: paste a pre-existing key, no browser needed
geogen login --api-key wsk_your_api_key_here

# Over SSH: get the URL, paste it into a browser on your laptop
geogen login --no-browser

# Custom device label (shows up in Settings → API Keys)
geogen login --device "macbook-pro"
```

## Credential resolution order

For any command (other than `login`), the CLI resolves credentials in this order. The first match wins:

<Steps>
  <Step title="CLI flag">
    ```bash theme={null}
    geogen workspace --api-key wsk_your_api_key_here
    ```

    Per-command override. Use it to run against a different workspace without changing anything else.
  </Step>

  <Step title="Environment variable">
    ```bash theme={null}
    export GEOGEN_API_KEY=wsk_your_api_key_here
    export GEOGEN_BASE_URL=https://api.geogen.io   # optional
    geogen workspace
    ```

    Best for CI/CD secrets.
  </Step>

  <Step title="Config file">
    The key written by `geogen login`, stored at `~/.geogen/config.json` (chmod 600 on POSIX).
  </Step>
</Steps>

## Logout

Clears the stored credentials:

```bash theme={null}
geogen logout
```

This only removes the local copy. To fully revoke access, also delete the key from **Settings → API Keys** in the dashboard.

## Inspect resolved config

`geogen config` prints the effective configuration and where each value came from:

```bash theme={null}
$ geogen config
Config file: /Users/you/.geogen/config.json
┌──────────┬─────────────┬────────┐
│ setting  │ value       │ source │
├──────────┼─────────────┼────────┤
│ api key  │ wsk_…ab12   │ file   │
│ base url │ https://api.geogen.io │ default │
└──────────┴─────────────┴────────┘
```

The API key is masked. Only the first and last four characters are shown.

## Config file format

`~/.geogen/config.json` is plain JSON:

```json theme={null}
{
  "apiKey": "wsk_your_api_key_here",
  "baseUrl": "https://api.geogen.io"
}
```

You can edit it manually if you prefer. Missing fields fall through to env vars, then defaults.

<Warning>
  Never commit `~/.geogen/config.json` or your API key to source control. For CI pipelines, use `GEOGEN_API_KEY` as a secret instead.
</Warning>

## Multiple workspaces

Each `geogen login` mints a new API key bound to whichever workspace you pick on the consent screen. To switch which workspace the CLI talks to, you have two options:

```bash theme={null}
# Re-run login and pick a different workspace
geogen login

# Or pass a different key per command
GEOGEN_API_KEY=wsk_other_workspace_key geogen entities list
```

## Security notes

The browser-based flow is designed so your API key never leaves your machine in plain text any longer than necessary:

* The local HTTP listener binds to **`127.0.0.1` only** (not exposed on your network).
* The listener accepts callbacks from **only the configured dashboard origin** (CORS-locked).
* A **cryptographically random `state` token** is exchanged through the URL. Any callback with the wrong state is rejected, defeating local-process impersonation.
* The listener **shuts down immediately** after receiving the key, or after a 5-minute timeout.

The API key itself is stored unencrypted in `~/.geogen/config.json` (chmod 600). If that's not acceptable for your environment, use `GEOGEN_API_KEY` env var injection from a secrets manager instead.

## Errors

| Symptom                                                | Likely cause                                                                                     |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `Login timed out after 300s.`                          | Browser flow didn't complete within 5 minutes. Re-run `geogen login`.                            |
| `Could not reach the CLI listener on your machine.`    | The browser tab is using a stale port and the CLI process already exited. Re-run `geogen login`. |
| `Callback state mismatch: refusing key.`               | Another process tried to send a key to the listener. Very unusual; re-run `geogen login`.        |
| `Only workspace owners and admins can create API keys` | The dashboard requires owner/admin role to mint API keys. Ask a workspace owner.                 |
| `Maximum of 5 API keys allowed per workspace.`         | Delete stale `CLI: ...` keys in **Settings → API Keys**, then retry.                             |
| `No API key found.`                                    | None of the three credential sources resolved a key. Run `geogen login`.                         |
| `Invalid API key format` / `HTTP 401`                  | Key was rejected by the server. Try `geogen login` again.                                        |