openhands-llm-auth

Implements OAuth dual-authentication for LLM providers in OpenHands-based applications.

Updated Aug 19, 2026
One-click install
npx skills add https://github.com/swcstudiospace/aimeecodes --skill openhands-llm-auth-swcstudiospace
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openhands-llm-auth
Source: https://github.com/swcstudiospace/aimeecodes/tree/main/.aimee/skills/openhands-llm-auth
Command: npx skills add https://github.com/swcstudiospace/aimeecodes --skill openhands-llm-auth-swcstudiospace

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? OpenHands-based apps like PrayerHands only support a single API key for LLM access, leaving no path for OAuth subscription logins such as SuperGrok or xAI device-code authentication. ## Core Features & Use Cases - Dual-auth settings model: Adds llm_auth_method plus OAuth token fields to the Settings model with secret-safe serialization and merge-on-store behavior. - Device-code OAuth routes: Dedicated endpoints for device code start, polling, refresh, status, and logout, wired into LiteLLM via setup_llm_config. - Frontend OAuth panel: React settings UI that shows the OAuth flow for xAI/Grok providers, hides the API-key field while connected, and polls with authorization_pending/slow_down handling. - Use Case: A user wants to log into PrayerHands with a SuperGrok subscription instead of an API key; this skill guides adding the xAI device-code flow end to end, from backend routes to the settings screen. ## Quick Start Add xAI OAuth device-code login to my OpenHands app so users can authenticate Grok models with their SuperGrok subscription instead of an API key.

Frequently Asked Questions about openhands-llm-auth

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add OAuth login to OpenHands LLM settings?▼

Add an `llm_auth_method` field plus OAuth token fields to the Settings model, create dedicated device-code/poll/refresh routes, and inject refreshed tokens into LiteLLM via `setup_llm_config`. The frontend shows an OAuth panel that hides the API-key field while connected.

How to implement xAI device code OAuth for Grok models?▼

Use the RFC 8628 device code flow against `https://auth.x.ai/oauth2/device/code` with the public Grok CLI client id, poll the token endpoint handling `authorization_pending` and `slow_down`, then use the access token as the LiteLLM API key with the `xai/` model prefix.

Why does xAI OAuth return 403 after successful browser login?▼

A 403 after successful login usually indicates a tier or entitlement restriction, not a bad token. Map it to a distinct error like `xai_oauth_tier_denied` without forcing re-login, and offer an API-key fallback through console.x.ai.

Can OpenHands settings store both API key and OAuth tokens?▼

Yes, the dual-auth pattern stores both, with `llm_auth_method` selecting the active method. GET responses must expose only booleans like `xai_oauth_set` and never return raw tokens, and POST merges preserve OAuth fields when omitted.

How do I run async token refresh from synchronous OpenHands code?▼

Conversation setup often runs inside an existing asyncio loop, so plain `asyncio.run` crashes. Run the refresh coroutine in a one-shot thread pool with its own loop to make it nested-loop safe.