hermes-skills-autonomous-ai-agents/hermes-agent/references/portal-auth-for-third-party-apps.md

# Nous Portal — authenticating third-party apps against the subscription

Recurring user question: "Can app X (Karakeep, OpenWebUI, LibreChat, OpenViking,
LangChain pipeline, n8n flow, etc.) use my Nous Portal subscription without me
copy-pasting an API key — ideally via the Portal login I already have?"

The honest answer has three architectural layers people conflate. Walk through
them in order before proposing solutions.

---

## Layer 1 — Is this thing a Hermes plugin, or a separate app?

This is the question to answer FIRST. The "OpenViking" case in particular
trips agents up.

| Surface | What it actually is | Auth path |
|---|---|---|
| **OpenViking memory plugin** (`plugins/memory/openviking/`) | Code that runs **inside the Hermes process**. Its LLM calls go through Hermes's already-configured provider. | Already uses Portal if user's Hermes is configured for Portal. Nothing extra needed. `OPENVIKING_API_KEY` is the OpenViking *server's* own auth, not LLM auth. |
| **OpenViking the standalone server** (separate container) | A separate context-DB service. If it ever calls an LLM on its own, that's a separate HTTP client. | Same as any external app — Layer 2/3 below. |
| **Karakeep, n8n, LibreChat, OpenWebUI, any self-hosted app** | Different process, often different machine. Makes its own HTTPS calls to `inference-api.nousresearch.com`. | Layer 2/3 below. |

**Pitfall to avoid**: do not pitch "OAuth into Portal" as the solution for a
plugin that already runs inside Hermes. That LLM call is already authenticated
via Hermes's provider config. The plugin's own server auth (e.g.
`OPENVIKING_API_KEY` for talking to the OpenViking REST API) is unrelated to
Portal.

---

## Layer 2 — For genuinely external apps, what does Portal actually expose?

Portal at `https://inference-api.nousresearch.com/v1` is an OpenAI-compatible
inference endpoint. It accepts **bearer-token authentication only**: either

1. **A static API key** from `portal.nousresearch.com → API Keys`, or
2. **An x402-protocol payment header** (Solana USDC, beta, anonymous, per-request).

There is **no general OAuth 2.0 authorization server**. There is no
"Sign in with Nous Portal" SSO that third-party apps can register as clients
against. There is no shared cookie or session that browser-Portal-login
extends to other apps on the same machine.

What Hermes Agent has that *feels* like OAuth — `hermes login --provider nous`
opening a browser, user signs in, token lands in `~/.hermes/auth.json` — is a
**Hermes-specific browser flow**. Under the hood it produces a credential
Hermes uses as a bearer. It is not a public OAuth provider that Karakeep et al.
can implement a client for, because it isn't an OAuth provider at all from the
outside.

---

## Layer 3 — Can we bridge the gap without Portal changing anything?

Yes. The pattern is a **local credential-broker proxy**. Even without a public
OAuth flow, an app on the user's machine can:

1. Read Hermes's existing Portal credential out of `~/.hermes/auth.json`.
2. Expose a local OpenAI-compatible endpoint at `http://localhost:NNNN/v1`.
3. Forward incoming requests to `inference-api.nousresearch.com/v1` with that
   bearer attached.

Karakeep/OpenWebUI/etc. then point at `http://localhost:NNNN/v1` with any
placeholder key. The user never copies their Portal key around — the proxy
rides on the credential Hermes already holds.

Where this could live in Hermes:

- `gateway/platforms/api_server.py` is the precedent — it exposes the agent
  over a local OpenAI-compatible endpoint, but routes through the full agent
  loop (tool calls and all). The proxy variant is **pure inference
  pass-through**: no agent loop, no tools, just forward `/chat/completions`
  upstream with the user's stored Portal bearer.
- ~150 lines as a new gateway adapter or a plugin under `plugins/`.
- Token refresh: if the browser-OAuth flow produces a refreshable token, the
  credential pool's refresh logic already exists. If it's a long-lived static
  bearer, even simpler.

This is genuinely useful and worth shipping — it's the answer to "use my
Portal sub with $external_app without copy-pasting keys."

---

## Real OAuth provider on Portal — when is it worth pitching?

Only when the consumer is *another first-party Nous thing* (a future SDK, a
Nous-branded extension, a Discord-bot integration that needs per-user
delegation, etc.). Pitching it as the answer to "use my Portal sub with
Karakeep" is selling the user a thing that won't reach them: even if Portal
shipped OAuth tomorrow, Karakeep's LLM-provider config UI is `base_url +
bearer_token` with no OAuth client, no callback handler, no token refresh.
The OpenAI ecosystem standardized on static bearers and downstream apps
won't rebuild their config UX to accommodate a new auth flow.

The features that would actually help users today, and that Portal could ship
without depending on third-party app changes:

- **Scoped, named, revocable API keys** with last-used timestamps. Same UX
  benefits people want from OAuth (revoke a compromised key, see what's using
  the sub, scope a key to specific models), in a shape every existing app
  already supports.
- **Per-key rate limits** so a noisy app can be capped without eating the
  user's headroom for Hermes itself.

---

## Talking-points cheatsheet (for next time)

When the user asks "can $APP use my Portal subscription":

1. First decide: Hermes plugin (runs inside Hermes) or separate app? If plugin,
   it already uses Portal via Hermes's provider config — done.
2. If separate app: today, paste the static API key from Portal → API Keys.
   Base URL `https://inference-api.nousresearch.com/v1`. Rate limits are
   subscription-tier based, applied per-key.
3. If the user pushes back with "but I don't want to paste a key" — that's
   the local-broker-proxy answer (Layer 3). Worth building. Not a Portal-side
   OAuth roadmap problem.
4. Mixed setup ("Portal for some things, OpenRouter/Ollama Cloud for the
   Hermes agent itself") is fully supported. Hermes treats agent
   provider/model and tool-side LLM calls as independent config; you can
   point each at a different endpoint.

**Note on the Tool Gateway**: the "no separate accounts, no API key juggling"
pitch in the Tool Gateway announcement is specifically about Hermes Agent's
*tools* (web search, browser, image gen, TTS) flowing through the Portal
subscription when Hermes is configured to use Portal as its provider. It is
**not** a claim that arbitrary third-party apps inherit Portal auth.