Docs / Use / Authentication

Authentication

Live ecosystem data comes from the Stellar Raven MCP server, which requires OAuth. kedgeway signs you in once and stores the token on your machine.

How login works

1. Dynamic client registration. kedgeway registers itself with Raven as a client named kedgeway with scope mcp. No client secret is baked into the tool.
2. PKCE. A code verifier is generated for the login and used to complete the code exchange.
3. Local callback. kedgeway starts a one-shot HTTP server on 127.0.0.1 to receive the redirect. It reuses the port from your last login when it can, otherwise the operating system picks one. The redirect carries a state value that must match, so stray requests are ignored.
4. Browser. The authorization URL is always printed to stderr. kedgeway also tries to open it with open (macOS), xdg-open (Linux) or start (Windows).
5. Token. The code is exchanged for a token and saved.

The callback waits up to 5 minutes for you to authorize.

When it asks you to log in

kedgeway login starts a fresh authorization: it clears the stored token, client registration and verifier first. login --export does not clear them. It prints what is already stored, and only starts a login when nothing is stored. kedgeway diagnose first tries your stored token silently, with no server and no browser. Only if Raven answers 401 does it start the interactive flow.

Where the token lives

~/.config/kedgeway/auth.json

The folder is created with mode 0700 and the file is written with mode 0600, through a temporary file and a rename. It holds the OAuth tokens, the client registration, and the last callback port.

To delete it:

kedgeway logout

What is sent to Raven

Only one fixed script, run through Raven's execute tool. It asks for the Software Versions page, the Scout toolchain index and a documentation search. It does not include anything from your repo. File names, manifests and versions stay on your machine; the comparison happens locally.

Headless login

Raven's OAuth server offers authorization code with PKCE and refresh tokens only, with no device-code grant, so there is no --device flow. On a machine without a browser, use:

kedgeway login --no-browser

kedgeway prints the authorization URL and does not try to open a browser. Open it in any browser and sign in. The browser is then redirected to http://127.0.0.1:<port>/callback, which only exists on the machine running kedgeway. Two ways to finish:

• Paste it back. Copy the full redirect URL (or just its code) into the terminal and press Enter. Bad input gets a one-line error and the prompt repeats.
• Forward the port. From your own machine, before you sign in, forward the callback port so the redirect lands on kedgeway directly. The port is in the redirect_uri of the printed URL.

ssh -L <port>:127.0.0.1:<port> user@remote-host

A pasted URL is checked against the login attempt's OAuth state, and the check fails closed: with no state to compare, a pasted URL is refused. A bare code carries no state, so it cannot be checked. When stdin is not a terminal, pasting is disabled and only the callback can finish the login.

For CI, do this once on a trusted machine and add --export to print the secret afterwards:

kedgeway login --no-browser --export

In CI

Run kedgeway login --export to print your stored credentials as a base64 secret, and put it in a KEDGEWAY_AUTH secret. At runtime the variable replaces auth.json: it is never written to disk and refreshes in memory only, so a rotated refresh token can make it go stale. See CI.

Troubleshooting

The port is busy

kedgeway falls back to a different free port on 127.0.0.1. Nothing to do.

The browser did not open

Copy the URL printed in the terminal (stderr) into a browser on the same machine. On a server with no browser, see Headless login.

Login timed out

The callback gives up after 5 minutes. Run kedgeway login again.

The token was rejected

kedgeway reports that authentication succeeded but Raven rejected the token. Run kedgeway logout, then kedgeway login.