Bug: Nous Portal OAuth device code flow broken; _nous_api_key() rejects valid API keys

[natehale]

Bug: Nous Portal OAuth device code flow — approval never propagates to token endpoint; _nous_api_key() rejects valid API keys

Summary

The OAuth device code flow for Nous Portal is broken: the verification URL shows a subscription plan page with no device approval UI, so the token endpoint never receives the approval signal. Additionally, _nous_api_key() in agent/auxiliary_client.py strictly validates tokens as JWTs, rejecting plain sk- API keys that the Portal's own API docs describe as the standard authentication method.

This blocks all Nous auxiliary tasks (compression, vision, skills_hub, etc.) for users who authenticate via API key.

Environment

• Hermes Agent v0.16.0 (editable install)
• Linux 6.8.0-110-generic
• Nous Portal account: Plus plan ($20/mo, paid-up)

Steps to Reproduce

1. Run hermes auth add nous --no-browser --timeout 300
2. CLI prints: https://portal.nousresearch.com/manage-subscription?user_code=XXXX-XXXX
3. Open the URL in a browser — it shows a subscription plan selection page, not a device approval page
4. Sign in to the Portal (Google/GitHub/email)
5. No "Approve Device" or similar UI appears
6. CLI continues polling: Waiting for approval (polling every 1s)...
7. Poll the token endpoint directly — it returns authorization_pending indefinitely

Verified with direct curl testing:

• Device code POST to /api/oauth/device/code → 200, returns device_code + user_code ✓
• Token poll POST to /api/oauth/token with device_code → authorization_pending for 150+ seconds, even after the user has signed into the Portal ✓
• No API endpoint exists to programmatically approve the device code

What Works

• The sk- API key from the Portal works perfectly for direct inference:

  curl -s https://inference-api.nousresearch.com/v1/chat/completions \
    -H "Authorization: Bearer $NOUS_API_KEY" \
    -d '{"model":"stepfun/step-3.7-flash:free","messages":[...]}'
  → 200, valid response
  

• The API docs at https://portal.nousresearch.com/api-docs confirm API keys are the standard auth method (Option 1: "Using API keys & account credits")

Root Cause

Two issues compound:

1. Portal-side: The device code verification URL (/manage-subscription?user_code=...) does not present a device approval UI. The approval never reaches the token endpoint. (Related: [Bug]: Nous Portal OAuth device code flow fails on servers/headless environments (Vercel error 249) #12275 — device code flow also fails from servers due to Vercel WAF)

2. Hermes-side: _nous_api_key() in agent/auxiliary_client.py (line ~1278) only accepts JWT tokens via _nous_invoke_jwt_is_usable(). Plain sk- API keys fail with access_token_not_jwt, even though:

   • The Portal API docs specify API key auth as the standard method
   • PR [Feature]: Nous Research Portal should be first-class provider option in setup #644 / feat: add Nous Portal API key provider (#644) #680 originally added nous-api as an API key provider, but it was removed in commit 013cc4d2f with the message: "Nous Portal only supports OAuth authentication"
   • The JWT-only fallback was also removed in 95cf8f984

Proposed Fix

In agent/auxiliary_client.py, update _nous_api_key() to accept sk- prefixed API keys without JWT validation:

def _nous_api_key(provider: dict) -> str:
    """Extract a usable Nous inference credential from stored auth state.

    Accepts both JWT tokens (minted by the Portal OAuth flow) and plain
    API keys (``sk-`` prefixed, generated on the Portal).  The inference
    API treats both as valid bearer tokens.
    """
    from hermes_cli.auth import _nous_invoke_jwt_is_usable

    for token_key, expiry_key in (
        ("agent_key", "agent_key_expires_at"),
        ("access_token", "expires_at"),
    ):
        token = provider.get(token_key)
        if not isinstance(token, str) or not token.strip():
            continue
        # Plain API keys (sk-...) are valid bearer tokens per the Portal
        # API docs — accept them without JWT validation.
        if token.startswith("sk-"):
            return token
        if _nous_invoke_jwt_is_usable(
            token,
            scope=provider.get("scope"),
            expires_at=provider.get(expiry_key),
        ):
            return token
    return ""

This is a minimal, backwards-compatible change — JWT tokens continue to work as before, and sk- API keys are additionally accepted.

Alternative / Longer-term

• Fix the Portal's device code approval UI — the verification URL should show an "Approve Device" button, not a subscription page
• Re-add nous-api as a provider (reverting 013cc4d2f) — gives users a proper setup wizard path for API key auth
• At minimum, document that hermes auth add nous --type api-key is the recommended path when OAuth is unavailable

References

• [Bug]: Nous Portal OAuth device code flow fails on servers/headless environments (Vercel error 249) #12275 — Device code flow fails on servers/headless (Vercel WAF)
• Nous Tool Gateway returns 401 despite successful Nous OAuth and managed tools available #22283 — Nous Tool Gateway 401 despite successful OAuth
• [Feature]: Nous Research Portal should be first-class provider option in setup #644 / PR feat: add Nous Portal API key provider (#644) #680 — Original nous-api provider addition
• Commit 013cc4d2f — Removal of nous-api provider
• Portal API docs: https://portal.nousresearch.com/api-docs
• OpenAPI spec: https://portal.nousresearch.com/api/openapi

[GottZ]

This was generated by AI during triage.

Summary

One PR (#48612) addresses this issue, adding acceptance of static Portal sk- API keys across the Nous credential-resolution paths (auth store, credential pool, runtime provider, auxiliary client) to fix the JWT-only rejection described in the report; it does not touch the OAuth device-code approval-propagation half of the root cause.

Related pull requests

• fix(nous): accept static api keys for runtime auth #48612 best fix — (+333/-21) — partial_fix: adds _nous_static_api_key_is_usable/_nous_runtime_token_is_usable so sk- keys are accepted in _nous_api_key(), credential_pool.runtime_api_key, resolve_nous_runtime_credentials(), and runtime_provider.py, matching the reported JWT-only rejection bug; it leaves the device-code verification-URL/approval-propagation half of the issue untouched, and per teknium1's [contributor:7327 commits] keep_open review the 401 recovery path (agent/conversation_loop.py:3802-3815, tests/agent/test_nous_oauth_401_guidance.py:47-49) still tells users with a rejected static key to reauthenticate via OAuth instead of replacing the API key.

Suggested consolidation

Continue with #48612 as the best available fix for the JWT-vs-API-key rejection bug, but despite it being the verify-stage's best fix, keep it open per teknium1's [contributor:7327 commits] keep_open review rather than merging as-is: the diff does not add static-key-specific 401 guidance or preserve/derive the resolved credential path at the 401 handler, so a rejected sk- key would still surface incorrect OAuth-reauth instructions. Address that gap (and its regression test) before merge; the OAuth device-code approval-propagation portion of #47950 remains unaddressed by any PR.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I47950(["issue #47950 (open)"])
    P48612["PR #48612 (open)"]
    P48612 -->|best fix| I47950
    class I47950 open
    class I47950 target
    class P48612 open
    class P48612 best
    click I47950 "https://github.com/NousResearch/hermes-agent/issues/47950"
    click P48612 "https://github.com/NousResearch/hermes-agent/pull/48612"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 22 kB of PR diffs, 6 kB of issue/PR text, 1 kB of discussion (1 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[teknium1]

Update — portal-side root cause located in nous-account-service (issues are disabled there, so recording the analysis here; needs a Linear ticket on the portal side).

Device-code approval UI silently never renders on /manage-subscription?user_code=… — CLI/Desktop poll to timeout

Symptom (multiple user reports)

User runs Hermes Agent login (CLI or Desktop), opens the printed
https://portal.nousresearch.com/manage-subscription?user_code=XXXX-XXXX,
and lands on the ordinary plans/account page. No "Allow Hermes Agent to
connect?" prompt, no code display, no error. The client polls
/api/oauth/token and gets authorization_pending until the code expires.

Reports:

• hermes-agent Bug: Nous Portal OAuth device code flow broken; _nous_api_key() rejects valid API keys #47950 (natehale, paid-up Plus plan, verified with direct curl: token endpoint returns authorization_pending for 150+ s after portal sign-in; no approval UI ever appears)
• Discord support (user witcheer, 2026-08-18): same symptom on both Mac Desktop app and CLI, Chrome + Safari, VPN disabled — logged-in account page renders, "None of the usual requests to enter the user-code".
• hermes-agent [Bug]: Nous Portal OAuth device code flow fails on servers/headless environments (Vercel error 249) #12275 is the sibling Vercel-WAF variant (server-side browsers blocked outright).

Root cause candidates (code-level)

The device-approval screen is DeviceConnectPanel, rendered conditionally in
src/app/manage-subscription/PlainSubscriptionManager.tsx (~L100):

if (
  s.isDeviceFlow &&
  (s.connectableOrgs.length > 0 || view.hasTeamMembership) &&
  !showFullManage
) { … render DeviceConnectPanel … }

connectableOrgs filters memberships to hasActiveSubscription || apiCreditsBalance > 0,
and memberships come from the server-side session (auth() in
manage-subscription/page.tsx). Two paths reproduce the reported symptom exactly:

1. SSR session miss. If auth() resolves null (stale/split Privy vs
   WorkOS cookies — note the WorkOS rollout flags from feat: inline security risk self-annotation for terminal tool #800), memberships
   is [], the panel is gated out, and the page renders the anonymous plan
   catalog while client-side hydration still shows the user as logged in.
   HermesPrivySessionSync runs exactly once (ranRef) and swallows a
   getAccessToken() failure, so there is no retry and no visible error.

2. Logged in, but no funded org and no team. A user whose orgs show no
   active subscription and zero credit balance (lapsed sub, or a
   classification/balance-projection edge) gets the panel gated out — even
   though subscriptionMachine.ts (~L267) documents the opposite design:
   "Linking is identity establishment, not a billing event — connect is
   deliberately NOT gated on subscription or credit state." The render gate
   contradicts the machine's own guard (DEVICE_CONNECT only requires
   isLoggedIn && isDeviceFlow).

Additionally: an unknown or expired user_code produces no error state at
page load. getDeviceAuthorizationContextByUserCode is only consulted for
orgHint (subscriptionData.ts ~L252); invalid_user_code /
expired_user_code only surface after clicking Connect — which the user can
never do when the panel doesn't render. Codes expire in 600 s, so a re-opened
stale link degrades to the identical silent blank outcome.

Suggested fixes

1. Render DeviceConnectPanel whenever s.isDeviceFlow && s.memberships.length > 0
   (drop the funded-org gate, matching the machine's design comment). The
   no-credits case already has copy for it (connectNowFundLaterCopy,
   currently unreachable for exactly the users who need it).
2. Show an explicit error state on page load for unknown/expired user_code
   ("This device code has expired. Start login again from the CLI." — the
   strings already exist in machineActors.ts).
3. Device flow + SSR-anonymous + client-session-present should force the
   refresh path (or at least render a prominent "Session expired — sign in
   again to approve this device" CTA) instead of one silent best-effort sync.

Impact

Every user who hits either path gets a dead-end login with zero feedback on
any surface: portal shows a normal page, CLI/Desktop show only a poll timeout.
This is currently a recurring support-thread shape.

[teknium1]

Portal-side fix PR is up: NousResearch/nous-account-service#932 — renders the device approval panel for any signed-in member (drops the funded-org gate) and shows explicit error copy for unknown/expired user codes instead of silently falling back to the plan catalog. Targeted jest suite passing (14/14). Awaiting portal-team review; not merged.