Hermes Agent OAuth vs API Key: Which Should You Use?

Choosing between Hermes Agent OAuth and an API key is not just a login preference. It decides which account pays, whether credentials refresh automatically, what happens when a subscription quota ends, and whether an unattended gateway or cron job can recover without a human.

This guide owns one intent: Hermes Agent OAuth vs API key. It explains the billing and reliability boundary, then gives you a small verification sequence that does not expose the credential.

OAuth and API keys pay through different accounts#

An API key normally bills a provider project or wallet directly. OAuth normally authorizes Hermes against a subscription or account entitlement. Those routes can reach similar models while consuming different balances.

Before selecting either route, write down four facts:

1. Provider: which company receives the request?
2. Authentication: OAuth, API key, local endpoint, or provider gateway?
3. Model ID: which exact model should answer?
4. Billing authority: which subscription, project, credit wallet, or cloud account should pay?

If you cannot answer all four, do not add a fallback yet. A fallback can make the request succeed while silently moving the bill to another account. The Hermes provider cost and rate-limit guide explains how to separate a healthy fallback from billing drift.

When OAuth is the better Hermes Agent choice#

Choose OAuth when all of these are true:

• Hermes documents an OAuth path for the provider.
• Your plan is eligible for that path.
• You prefer browser or device-code login over handling a static secret.
• The route's quota and billing rules fit the workload.
• The credential can refresh reliably in the runtime that owns the session.

OAuth is especially convenient for an interactive workstation. hermes model can launch the supported authorization flow, Hermes can store refreshable credentials in its auth store, and you avoid copying a long token into a shell or editor.

OAuth does not mean unlimited. A successful login proves identity, not quota. A later 403 can indicate an entitlement restriction; a 429 can mean the account or model is rate-limited. Check the provider's current billing surface before assuming the login covers unattended agent use.

When an API key is the better choice#

Choose a direct API key when you need:

• a provider project with a clear spend cap;
• separate production and development credentials;
• service operation that must not depend on an interactive browser login;
• explicit organization, region, or cloud-project billing;
• a provider whose consumer subscription is not supported by Hermes;
• controlled key rotation and revocation through your existing secret-management process.

A key is easier to scope operationally, but it is also easier to leak. Put secrets in the active profile's .env, not in config.yaml, prompts, screenshots, shell history, Git, support threads, or content files. Use hermes config env-path to find the correct file and the Hermes Agent API-key safety guide for the complete setup checklist.

Current Hermes authentication paths#

Hermes supports several authentication patterns. Availability changes, so use the current hermes model picker and official provider documentation as the source of truth.

Nous Portal OAuth#

For the Nous-native route, hermes setup --portal can configure OAuth, a model provider, and supported Tool Gateway routing together. Use hermes portal info to inspect the current login and routing. This is different from pasting a direct provider key: usage is attached to the Portal account and subscription rules.

OpenAI Codex OAuth#

Hermes can authenticate the Codex provider through a device-code flow and keep credentials in its auth store. If a refresh grant is revoked, re-authenticate the route rather than pasting an unrelated OpenAI API key and assuming it is the same billing path. Direct OpenAI API usage is a separate provider route.

GitHub Copilot authentication#

Copilot can use supported OAuth or GitHub token types and may also discover an existing authenticated GitHub CLI session. A classic token is not automatically valid for Copilot requests. Prove the exact Copilot route with a tiny model call before depending on it for a coding workflow.

Anthropic subscription OAuth vs API key#

A Claude subscription and an Anthropic API organization are separate billing surfaces. Current Hermes documentation says the supported Anthropic OAuth path requires an eligible Claude Max setup with extra-usage credits; a direct ANTHROPIC_API_KEY uses pay-per-token API billing instead. Do not treat a successful Claude app login as proof that Hermes API work is included.

xAI, Qwen, MiniMax, and other OAuth routes#

Some providers expose subscription OAuth while also supporting direct API keys. Eligibility, quotas, and model catalogs can differ. Treat an OAuth 403 as a plan or entitlement question before rotating secrets. Treat a direct-key 402 as a balance question before rebuilding the gateway.

Local endpoints#

Ollama and local models may not need an API key on loopback. That removes cloud credential billing, not operational limits: model context, tool calling, RAM or VRAM, host uptime, and queue capacity still matter.

Use the correct setup command#

Hermes has two model commands with different jobs:

# Outside a session: configure a new provider or authenticate
hermes model

# Inside a session: switch among routes already configured
/model

If a provider has never been configured, use hermes model. Do not expect /model inside a running chat to perform every OAuth or key setup flow.

For a profile-specific agent, include the profile explicitly:

hermes -p work model
hermes -p work config env-path
hermes -p work doctor
hermes -p work chat -q "Reply with exactly: provider ok"

The profile matters because each profile can have its own .env, configuration, model choice, gateway, and scheduled jobs. Read the Hermes profiles guide before sharing one credential across personal and production agents.

Store secrets in the right place#

Use this rule:

• .env: API keys, bot tokens, passwords, and other secrets.
• config.yaml: provider ID, model name, timeouts, terminal backend, and other non-secret settings.
• auth.json: OAuth credentials managed by Hermes; do not copy or publish it.

Find the active files instead of assuming the default profile:

hermes config path
hermes config env-path
hermes config check

For a long-running gateway, verify the service uses the same profile and Hermes home as the terminal where you tested the provider. A CLI success under the default profile does not prove a Telegram bot running under another profile inherited the same auth.

The five-minute verification sequence#

Run this before configuring Telegram, Discord, browser automation, or scheduled jobs:

hermes doctor
hermes config get model
hermes chat -q "Reply with exactly: provider ok"

Then check the provider's own dashboard or hermes portal info where applicable. Verify that the expected account recorded the request. The answer text alone cannot prove which wallet paid.

Next, test one small tool-using task. Agent work can require more than one model request, and auxiliary tasks such as compression or session search may use their own configured routes. Inspect /usage, dashboard analytics, or provider usage after the representative run.

Only after those checks pass should you add provider fallbacks, Telegram, Discord, or scheduled agent work.

Diagnose errors by layer#

401: credential rejected#

The key may be invalid, revoked, copied incorrectly, or loaded from the wrong profile. For OAuth, the access or refresh credential may have expired or been revoked. Re-authenticate the same provider route; do not substitute another billing path without deciding to do so.

402: payment or credit problem#

The credential can be valid while its API wallet is empty. Open the provider billing page, confirm the expected organization or project, and check whether a fallback attempted a different route.

403: permission or entitlement problem#

The account may be authenticated but not eligible for the model or OAuth product. Confirm plan eligibility, model access, project permissions, and region restrictions.

429: rate or quota limit#

A 429 is not usually fixed by repasting the key. Check request and token limits, concurrent subagents, context size, reasoning level, retries, and scheduled-job frequency. The token-overhead guide helps identify repeated large-context calls.

CLI works, gateway fails#

Check the gateway's profile, process environment, provider selection, and current logs. Long-running services can retain an older environment until reloaded. Use the gateway troubleshooting runbook and verify a real reply in the exact chat or thread.

OAuth reliability for gateways and cron jobs#

Unattended work changes the decision. A human can complete a device-code login on a laptop; a scheduled job at 03:00 cannot. For production-like jobs:

• verify refresh behavior before relying on OAuth;
• record which account owns the grant;
• monitor typed auth, entitlement, credit, and rate-limit errors separately;
• pin the intended provider and model when billing drift would be dangerous;
• keep the job's delivery target explicit;
• require the real report, file, or message as completion evidence.

If a workflow is important enough to run while you sleep, perform one controlled expiry, balance, or fallback drill. The Hermes cron recovery guide covers delivery and run-history checks; the self-hosted vs hosted responsibility matrix shows who owns recovery.

Rotate a key without breaking every agent#

1. Inventory the profiles and services that use the old key.
2. Create a new provider credential with the minimum practical scope.
3. Update one non-production profile and run the smoke test.
4. Update the production profile's secret file without printing the value.
5. Reload the owning long-running process.
6. Verify one real workflow and the provider-side usage record.
7. Revoke the old key only after every intended consumer has moved.
8. Search repositories, logs, screenshots, and support artifacts for accidental exposure.

Do not put the same unrestricted key into every profile for convenience. Separate profiles provide state boundaries, but a shared host user can still expose normal CLI credentials unless you deliberately isolate its tool environment.

The practical decision#

Choose OAuth for supported subscription convenience and managed credential refresh. Choose an API key for explicit project billing, environment separation, service operation, and spend controls. In both cases, prove the route and payer before adding autonomous work.

If credential operations are part of the control you want, self-host Hermes and use the secure server guide. If the outcome matters more than maintaining provider keys, balances, gateways, and uptime, compare FlyHermes pricing.