CLI Authentication

Authenticate CLIs and AI agents in two clicks

No API-key paste, no env-var hunt. Claude Code, Cursor, or any MCP-capable agent connects to your RoboTrace project via the OAuth Device Authorization Grant flow — the same pattern gh auth login and aws sso login use.

Common prompts

Paste any of these into Claude Code (with the robotrace plugin installed). The skill auto-invokes from the trigger phrase — no need to type the skill name.

IntegrateUse the RoboTrace skill to integrate observability into this project
IntegrateSet up RoboTrace for this ROS 2 robot
QueryShow me the last 5 failed missions on warehouse-amr-001
QueryWhich robots haven't reported in the last hour?
DebugMission a3b1c2 failed — pull the trace tree and tell me what went wrong
ProvisionProvision a new device called ur5-cell-3, MoveIt 2 manipulator
AuthAuthenticate me with RoboTrace
AuthLog out of RoboTrace and clear local credentials

How the flow works

terminal                     dashboard browser
─────────                    ─────────────────
$ claude
> /robotrace-integrate
Claude: Open
  https://robotrace.cloud/device
  and enter code: ABCD-1234
  (waiting...)             →   /device
                                  enter code: ABCD-1234
                                  [ Continue ]
                                  ↓
                                  Authorize: Claude Code (MCP)
                                  - read fleet
                                  - write fleet
                                  [ Authorize ]
                                  ↓
Claude: ✓ Authenticated         ✓ Return to terminal
        (token saved to
         ~/.config/robotrace/
         credentials.json,
         valid for 90 days)

Set up

One-time install of the MCP server; every Claude Code session after that uses it automatically.

1

Install via Claude Code plugin marketplace (recommended)

One command in any Claude Code session adds the RoboTrace marketplace and installs the plugin. The plugin bundles four skills plus the MCP server connection — no Python install, no settings.json edit. Hosted at github.com/ParagDD/robotrace-platform.
bash# In any Claude Code session:
> /plugin marketplace add ParagDD/robotrace-platform
> /plugin install robotrace@robotrace-cloud
> /reload-plugins

# That's it. The plugin bundles:
#   - 4 skills  (quickstart, integrate, setup-ros2, best-practices)
#   - 12 MCP tools  (authenticate, list_missions, query_telemetry, ...)
#
# Now ask Claude anything:
> Use the RoboTrace skill to integrate observability into this project
2

(Alternative) install MCP server manually

For Cursor, Windsurf, or any other MCP-capable agent that doesn't read the Claude Code plugin format, install the robotrace-mcp Python package directly. The agent spawns it as a subprocess and talks to your RoboTrace project via the REST API.
bash# 1. Install the MCP server
pip install robotrace-mcp

# 2. Wire it into Claude Code (~/.claude/settings.json)
#    or Cursor (~/.cursor/mcp.json) or any other MCP-capable agent
{
  "mcpServers": {
    "robotrace": {
      "command": "robotrace-mcp"
    }
  }
}

# 3. In any session, just ask
> /robotrace-integrate
# or
> Use the RoboTrace skill to authenticate me
3

Authenticate

The first time any MCP tool runs (or you explicitly ask Claude Code to authenticate), the server prints a short code and opens /device in your browser. Sign in if needed, click Authorize, return to your terminal. The agent picks up the token automatically within ~5 seconds.
4

Use any MCP tool

The token is stored at ~/.config/robotrace/credentials.json with 0600 permissions. All MCP tools — list_missions, get_mission, query_telemetry, provision_device, and the rest — use it transparently. Valid for 90 days.
5

Revoke when needed

Compromised machine, contractor offboarding, or just routine hygiene — revoke any authorized client from /settings/connected-apps. Existing tokens get rejected on the next API call.
bash# Browser:
https://robotrace.cloud/settings/connected-apps
# -> Find the entry  ->  [ Revoke ]

# Or locally (deletes the token from disk, but doesn't
# revoke it server-side — for full revocation use the
# dashboard):
python -c "from robotrace_mcp import credentials; credentials.revoke()"

Security model

  • RFC 8628 compliant. Standard OAuth Device Authorization Grant — the same flow used by GitHub CLI, AWS SSO, gcloud, kubectl OIDC-login.
  • User-bound consent. Every CLI authorization happens through your dashboard session — the platform never trusts a CLI to claim an identity unilaterally.
  • Scoped tokens. Each token has explicit read:fleet and/or write:fleet scopes shown to you before you authorize.
  • 90-day default lifetime, with full audit trail in /settings/connected-apps. Instant revoke. No refresh-token escalation paths.
  • 10-minute code window. User codes expire 10 min after generation. Re-running the CLI gets a fresh code; old ones can't be replayed.
  • No secret-in-URL. The verification URL displays only a short, low-entropy user code — the actual access token never travels over a URL or appears in browser history. It's delivered to the CLI's polling endpoint, then stored locally with 0600 file permissions.

Troubleshooting

My browser didn't open automatically
Headless / SSH / WSL / locked-down environments often block webbrowser.open(). The CLI also prints the verification URL — copy/paste it into any browser on any device.
Code says "expired"
Codes only last 10 minutes. Re-run the CLI; you'll get a fresh code instantly.
CLI keeps polling forever
Make sure you actually clicked Authorize (not just typed the code). The CLI also times out after ~10 min and exits with timeout if no decision was made.
Tokens 401 on a previously-working CLI
Either revoked (check /settings/connected-apps) or expired (90 days). Re-authenticate by running any MCP tool — it'll trigger a fresh device flow.

For SDK and API users

This OAuth flow is specifically for no-browser clients — CLIs, AI agents, MCP servers. For the robotrace-sdk Python package that runs on your robots, continue to use long-lived API keys provisioned at /settings/api-keys: robots need stable credentials that survive reboot, not an interactive login flow.

The same backend api_keys table stores both kinds of tokens, distinguished by a Device: prefix on the display name. So your /settings/api-keys and /settings/connected-apps pages stay separate and uncluttered.