[Feature] OAuth 2.0 Device Authorization Grant (RFC 8628) for CLI/headless authentication

[clouatre]

Is your feature request related to a problem? Please describe.

CLI tools and headless applications cannot use browser-based OAuth flows. The current hf auth login requires users to manually copy-paste tokens from the dashboard, which is error-prone and breaks the developer flow.

I'm building a Rust CLI for OSS contribution triage that needs HF Inference API access. With the rise of AI-powered CLI tools (Claude Code, Codex CLI, Block Goose, Mistral Vibe CLI, etc.), there's growing demand for seamless CLI authentication without manual token handling.

Describe the solution you'd like

Implement OAuth 2.0 Device Authorization Grant (RFC 8628):

1. CLI calls POST /oauth/device/code with client_id and optional scope
2. Hugging Face returns device_code, user_code, verification_uri, expires_in, interval
3. CLI displays: "Visit https://huggingface.co/device and enter code: XXXX-XXXX"
4. CLI polls POST /oauth/device/token with device_code (respecting interval)
5. User authorizes in browser
6. Hugging Face returns access_token

Proposed Python API:

from huggingface_hub import device_login

# Opens browser prompt, polls for completion
device_login()  # "Visit https://huggingface.co/device and enter code: XXXX-XXXX"

Describe alternatives you've considered

• Current flow (hf auth login): Requires manual token copy-paste from dashboard
• interpreter_login() / notebook_login(): Browser-dependent, not suitable for headless environments
• Environment variables: Works but requires users to manage token lifecycle manually

Additional context

Prior art:

• GitHub: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
• Google: https://developers.google.com/identity/protocols/oauth2/limited-input-device
• AWS CLI: aws sso login --use-device-code

Use cases:

• Rust/Go/Python CLI tools using HF Inference API
• SSH sessions without browser access
• Desktop apps without embedded browser
• Initial authentication for AI coding assistants

Timing: With the 1.0 release imminent (#3340) and CLI refactor using Typer complete, this could be a great addition for the stable API.

Suggested token design (following GitHub's approach):

• Access tokens: Long-lived (no expiry), matching current HF token behavior
• Scopes: Supported via scope parameter in initial /device/code request
• Refresh tokens: Optional future enhancement if short-lived tokens are preferred

[Wauplin]

Hi @clouatre , thanks for the detailed feature request! We've already discussed this internally in the past but did not prioritized it yet. I'll check internally and let you know if/when we decide to move forward on it.

For any other user landing on this page, please drop a comment/reaction if interested (will help to gauge interest).

Timing: With the 1.0 release imminent (#3340) and CLI refactor using Typer complete, this could be a great addition for the stable API.

Actually the 1.0 has been successfully shipped in late Oct' 25! 🤗 Just realized we did not close the issue about it. You can check out

• the release notes https://github.com/huggingface/huggingface_hub/releases/tag/v1.0.0
• and the related blog post https://huggingface.co/blog/huggingface-hub-v1