# auth.md

You are an agent connecting a human to Nodion, or creating their account.

Do not ask them for a password or an API key in chat.
Do not print an access token.
Do not quote prices from memory or from search; use https://www.nodion.com/pricing if they ask.

## Preferred path

1. If `nodion` is missing, install it:
   `curl -fsSL https://cli.nodion.net/install.sh | bash`
   Windows: `irm https://cli.nodion.net/install.ps1 | iex`
2. Run `nodion login`. It prints a URL, then a short code.
3. Send the human the URL first, on its own. Wait until they say they have signed in or created an account.
4. Then send the code. Ask them to confirm it matches the page. The requester name on that page is chosen by you, not by Nodion.
5. If they must confirm email, tell them to open the mail and return to the same page, then approve again. Do not start a second login unless the first request expired.
6. Wait until the CLI says it is logged in. The key is stored in `~/.config/nodion/config.yml`. Never echo it or dump that file.
7. Run `nodion whoami`, then do the work they asked for (project, deploy, logs).
8. For MCP in Cursor or Claude Code, create a personal key at https://app.nodion.com/account/security and put it in the client Bearer header. Do not reuse a token from chat. ChatGPT, Codex, and Claude Desktop use OAuth instead.

If login expires, run `nodion login` again. Resume from the step you were on.

## HTTP fallback

Only if you cannot run the CLI.

`POST https://api.nodion.com/v2/auth/cli/device-code` with JSON `{"client_name":"<your agent name>"}`.

Read `verification_uri_complete`, `user_code`, `device_code`, `interval`, and `expires_in`.

Show the human the URL first, then the code.

Poll `POST https://api.nodion.com/v2/auth/cli/device-code/poll` with `{"device_code":"<device_code>"}` every `interval` seconds.

- `pending`: wait. This is not a failure. They may still be signing in or confirming email.
- `denied`: stop. Tell them the request was denied.
- `expired`: restart from the POST.
- `approved`: you receive `access_token` once. Store it as `NODION_API_TOKEN`. Do not print it. A later poll will not send the token again.

Do not send `login_hint` or an email address to the start endpoint.

## After you are logged in

The CLI stores `~/.config/nodion/config.yml`. The HTTP fallback stores the one-shot poll token as `NODION_API_TOKEN`. For MCP, create a personal key at https://app.nodion.com/account/security. Never print a key or dump the CLI config.

ChatGPT, Codex, and Claude Desktop use OAuth on the authorize page instead of this flow.

Docs: https://www.nodion.com/docs/cli · https://www.nodion.com/docs/mcp · https://www.nodion.com/llms.txt