Hugging Face's logo

Hub Python Library documentation

OAuth and FastAPI

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.31.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

OAuth and FastAPI

OAuth is an open standard for access delegation, commonly used to grant applications limited access to a user’s information without exposing their credentials. When combined with FastAPI it allows you to build secure APIs that allow users to log in using external identity providers like Google or GitHub. In a usual scenario:

  • FastAPI will define the API endpoints and handles the HTTP requests.
  • OAuth is integrated using libraries like fastapi.security or external tools like Authlib.
  • When a user wants to log in, FastAPI redirects them to the OAuth provider’s login page.
  • After successful login, the provider redirects back with a token.
  • FastAPI verifies this token and uses it to authorize the user or fetch user profile data.

This approach helps avoid handling passwords directly and offloads identity management to trusted providers.

Hugging Face OAuth Integration in FastAPI

This module provides tools to integrate Hugging Face OAuth into a FastAPI application. It enables user authentication using the Hugging Face platform including mocked behavior for local development and real OAuth flow for Spaces.

OAuth Overview

The attach_huggingface_oauth function adds login, logout, and callback endpoints to your FastAPI app. When used in a Space, it connects to the Hugging Face OAuth system. When used locally it will inject a mocked user. Click here to learn more about adding a Sign-In with HF option to your Space

How to use it?

from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth
from fastapi import FastAPI, Request

app = FastAPI()
attach_huggingface_oauth(app)

@app.get("/")
def greet_json(request: Request):
    oauth_info = parse_huggingface_oauth(request)
    if oauth_info is None:
        return {"msg": "Not logged in!"}
    return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"}
You might also be interested in [a practical example that demonstrates OAuth in action](https://huggingface.co/spaces/medoidai/GiveBackGPT/blob/main/src/main.py)

attach_huggingface_oauth

huggingface_hub.attach_huggingface_oauth

< >

( app: fastapi.FastAPI route_prefix: str = '/' )

Add OAuth endpoints to a FastAPI app to enable OAuth login with Hugging Face.

How to use:

  • Call this method on your FastAPI app to add the OAuth endpoints.
  • Inside your route handlers, call parse_huggingface_oauth(request) to retrieve the OAuth info.
  • If user is logged in, an OAuthInfo object is returned with the user’s info. If not, None is returned.
  • In your app, make sure to add links to /oauth/huggingface/login and /oauth/huggingface/logout for the user to log in and out.

Example:

from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth

# Create a FastAPI app
app = FastAPI()

# Add OAuth endpoints to the FastAPI app
attach_huggingface_oauth(app)

# Add a route that greets the user if they are logged in
@app.get("/")
def greet_json(request: Request):
    # Retrieve the OAuth info from the request
    oauth_info = parse_huggingface_oauth(request)  # e.g. OAuthInfo dataclass
    if oauth_info is None:
        return {"msg": "Not logged in!"}
    return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"}

parse_huggingface_oauth

huggingface_hub.parse_huggingface_oauth

< >

( request: fastapi.Request )

Returns the information from a logged in user as a OAuthInfo object.

For flexibility and future-proofing, this method is very lax in its parsing and does not raise errors. Missing fields are set to None without a warning.

Return None, if the user is not logged in (no info in session cookie).

See attach_huggingface_oauth() for an example on how to use this method.

OAuthOrgInfo

class huggingface_hub.OAuthOrgInfo

< >

( sub: str name: str preferred_username: str picture: str is_enterprise: bool can_pay: typing.Optional[bool] = None role_in_org: typing.Optional[str] = None pending_sso: typing.Optional[bool] = None missing_mfa: typing.Optional[bool] = None )

Parameters

  • sub (str) — Unique identifier for the org. OpenID Connect field.
  • name (str) — The org’s full name. OpenID Connect field.
  • preferred_username (str) — The org’s username. OpenID Connect field.
  • picture (str) — The org’s profile picture URL. OpenID Connect field.
  • is_enterprise (bool) — Whether the org is an enterprise org. Hugging Face field.
  • can_pay (Optional[bool], optional) — Whether the org has a payment method set up. Hugging Face field.
  • role_in_org (Optional[str], optional) — The user’s role in the org. Hugging Face field.
  • pending_sso (Optional[bool], optional) — Indicates if the user granted the OAuth app access to the org but didn’t complete SSO. Hugging Face field.
  • missing_mfa (Optional[bool], optional) — Indicates if the user granted the OAuth app access to the org but didn’t complete MFA. Hugging Face field.

Information about an organization linked to a user logged in with OAuth.

OAuthUserInfo

class huggingface_hub.OAuthUserInfo

< >

( sub: str name: str preferred_username: str email_verified: typing.Optional[bool] email: typing.Optional[str] picture: str profile: str website: typing.Optional[str] is_pro: bool can_pay: typing.Optional[bool] orgs: typing.Optional[typing.List[huggingface_hub._oauth.OAuthOrgInfo]] )

Parameters

  • sub (str) — Unique identifier for the user, even in case of rename. OpenID Connect field.
  • name (str) — The user’s full name. OpenID Connect field.
  • preferred_username (str) — The user’s username. OpenID Connect field.
  • email_verified (Optional[bool], optional) — Indicates if the user’s email is verified. OpenID Connect field.
  • email (Optional[str], optional) — The user’s email address. OpenID Connect field.
  • picture (str) — The user’s profile picture URL. OpenID Connect field.
  • profile (str) — The user’s profile URL. OpenID Connect field.
  • website (Optional[str], optional) — The user’s website URL. OpenID Connect field.
  • is_pro (bool) — Whether the user is a pro user. Hugging Face field.
  • can_pay (Optional[bool], optional) — Whether the user has a payment method set up. Hugging Face field.
  • orgs (Optional[List[OrgInfo]], optional) — List of organizations the user is part of. Hugging Face field.

Information about a user logged in with OAuth.

OAuthInfo

class huggingface_hub.OAuthInfo

< >

( access_token: str access_token_expires_at: datetime user_info: OAuthUserInfo state: typing.Optional[str] scope: str )

Parameters

  • access_token (str) — The access token.
  • access_token_expires_at (datetime.datetime) — The expiration date of the access token.
  • user_info (OAuthUserInfo) — The user information.
  • state (str, optional) — State passed to the OAuth provider in the original request to the OAuth provider.
  • scope (str) — Granted scope.

Information about the OAuth login.

< > Update on GitHub

←Serialization