- - - - -OAuth2¶ -Generic client¶ -A generic OAuth2 class is provided to adapt to any OAuth2-compliant service. You can instantiate it like this: -from httpx_oauth.oauth2 import OAuth2 - -client = OAuth2( - "CLIENT_ID", - "CLIENT_SECRET", - "AUTHORIZE_ENDPOINT", - "ACCESS_TOKEN_ENDPOINT", - refresh_token_endpoint="REFRESH_TOKEN_ENDPOINT", - revoke_token_endpoint="REVOKE_TOKEN_ENDPOINT", -) - -Note that refresh_token_endpoint and revoke_token_endpoint are optional since not every services propose to refresh and revoke tokens. -Available methods¶ -get_authorization_url¶ -Returns the authorization URL where you should redirect the user to ask for their approval. - -Parameters - -redirect_uri: str: Your callback URI where the user will be redirected after the service prompt. -state: str = None: Optional string that will be returned back in the callback parameters to allow you to retrieve state information. -scope: Optional[List[str]] = None: Optional list of scopes to ask for. -code_challenge: Optional[str] = None: Optional code_challenge in a PKCE context. -code_challenge_method: Optional[Literal["plain", "S256"]] = None: Optional code_challenge_method in a PKCE context. -extras_params: Optional[Dict[str, Any]] = None: Optional dictionary containing parameters specific to the service. - - - -Example -authorization_url = await client.get_authorization_url( - "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], -) - - -get_access_token¶ -Returns an OAuth2Token object for the service given the authorization code passed in the redirection callback. -Raises a GetAccessTokenError if an error occurs. - -Parameters - -code: str: The authorization code passed in the redirection callback. -redirect_uri: str: The exact same redirect_uri you passed to the authorization URL. -code_verifier: Optional[str]: Optional code verifier in a PKCE context. - - - -Example -access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") - - -refresh_token¶ -Returns a fresh OAuth2Token object for the service given a refresh token. -Raises a RefreshTokenNotSupportedError if no refresh_token_endpoint was provided. - -Parameters - -refresh_token: str: A valid refresh token for the service. - - - -Example -access_token = await client.refresh_token("REFRESH_TOKEN") - - -revoke_token¶ -Revokes a token. -Raises a RevokeTokenNotSupportedError if no revoke_token_endpoint was provided. - -Parameters - -token: str: A token or refresh token to revoke. -token_type_hint: str = None: Optional hint for the service to help it determine if it's a token or refresh token. Usually either token or refresh_token. - - - -Example -await client.revoke_token("TOKEN") - - -get_id_email¶ -Returns the id and the email (if available) of the authenticated user from the API provider. It assumes you have asked for the required scopes. -Raises a GetIdEmailError if an error occurs. - -Parameters - -token: str: A valid access token. - - - -Example -user_id, user_email = await client.get_id_email("TOKEN") - - -OAuth2Token class¶ -This class is a wrapper around a standard Dict[str, Any] that bears the response of get_access_token. Properties can vary greatly from a service to another but, usually, you can get access token like this: -access_token = token["access_token"] - -is_expired¶ -A utility method is provided to quickly determine if the token is still valid or needs to be refreshed. - -Example -if token.is_expired(): - token = await client.refresh_token(token["refresh_token"]) - # Save token to DB - -access_token = token["access_token"] -# Do something useful with this access token - - -Provided clients¶ -We provide several ready-to-use clients for widely used services with configured endpoints and specificites took into account. -OpenID¶ -Generic client for providers following the OpenID Connect protocol. Besides the Client ID and the Client Secret, you'll have to provide the OpenID configuration endpoint, allowing the client to discover the required endpoints automatically. By convention, it's usually served under the path .well-known/openid-configuration. -from httpx_oauth.clients.openid import OpenID - -client = OpenID("CLIENT_ID", "CLIENT_SECRET", "https://example.fief.dev/.well-known/openid-configuration") - - -❓ refresh_token: depends if the OpenID provider supports it -❓ revoke_token: depends if the OpenID provider supports it - -Discord¶ -from httpx_oauth.clients.discord import DiscordOAuth2 - -client = DiscordOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -✅ revoke_token - - -Warning about get_id_email -Email is optional for Discord accounts, so the email might be None. - -Facebook¶ -from httpx_oauth.clients.facebook import FacebookOAuth2 - -client = FacebookOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -❌ refresh_token -❌ revoke_token - -get_long_lived_access_token¶ -Returns an OAuth2Token object with a long-lived access token given a short-lived access token. -Raises a GetLongLivedAccessTokenError if an error occurs. - -Parameters - -token: str: A short-lived access token given by get_access_token. - - - -Example -long_lived_access_token = await client.get_long_lived_access_token("TOKEN") - - -GitHub¶ -from httpx_oauth.clients.github import GitHubOAuth2 - -client = GitHubOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -❌ revoke_token - - -Tip -You should enable Email addresses permission in the Permissions & events section of your GitHub app parameters. You can find it at https://github.com/settings/apps/{YOUR_APP}/permissions. - - -Refresh tokens are not enabled by default -Refresh tokens are currently an optional feature you need to enable in your GitHub app parameters. Read more. - -Google¶ -from httpx_oauth.clients.google import GoogleOAuth2 - -client = GoogleOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -✅ revoke_token - -Kakao¶ -from httpx_oauth.clients.kakao import KakaoOAuth2 - -client = KakaoOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -✅ revoke_token - -LinkedIn¶ -from httpx_oauth.clients.linkedin import LinkedInOAuth2 - -client = LinkedInOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token (only for selected partners) -❌ revoke_token - -NAVER¶ -from httpx_oauth.clients.naver import NaverOAuth2 - -client = NaverOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -✅ revoke_token - -Okta¶ -Based on the OpenID client. You need to provide the domain of your Okta domain for automatically discovering the required endpoints. -from httpx_oauth.clients.okta import OktaOAuth2 - -client = OktaOAuth2("CLIENT_ID", "CLIENT_SECRET", "example.okta.com") - - -✅ refresh_token -✅ revoke_token - -Reddit¶ -from httpx_oauth.clients.reddit import RedditOAuth2 - -client = RedditOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -✅ refresh_token -✅ revoke_token - - -Warning about get_id_email -Reddit API never return email addresses. Thus, e-mail will always be None. - -FranceConnect¶ -from httpx_oauth.clients.franceconnect import FranceConnectOAuth2 - -client = FranceConnectOAuth2("CLIENT_ID", "CLIENT_SECRET") - - -❌ refresh_token -❌ revoke_token - - -Integration server -Since you need to go through a heavy validation process before getting your client ID and secret, you can use during development the integration server with demo credentials. You can enable this mode by setting the integration flag to True. -from httpx_oauth.clients.franceconnect import FranceConnectOAuth2 - -client = FranceConnectOAuth2("CLIENT_ID", "CLIENT_SECRET", integration=True) - - -Shopify¶ -The OAuth2 client for Shopify allows you to authenticate shop owners so your app can make calls to the Shopify Admin API. Besides the Client ID and Secret, you'll need the shop subdomain of the shop you need to access. -from httpx_oauth.clients.shopify import ShopifyOAuth2 - -client = ShopifyOAuth2("CLIENT_ID", "CLIENT_SECRET", "my-shop") - - -❌ refresh_token -❌ revoke_token - - -get_id_email is based on the Shop resource -The implementation of get_id_email calls the Get Shop endpoint of the Shopify Admin API. It means that it'll return you the ID of the shop and the email of the shop owner. - -Customize HTTPX client¶ -By default, requests are made using httpx.AsyncClient with default parameters. If you wish to customize settings, like setting timeout or proxies, you can do this by overloading the get_httpx_client method. -from typing import AsyncContextManager - -import httpx -from httpx_oauth.oauth2 import OAuth2 - - -class OAuth2CustomTimeout(OAuth2): - def get_httpx_client(self) -> AsyncContextManager[httpx.AsyncClient]: - return httpx.AsyncClient(timeout=10.0) # Use a default 10s timeout everywhere. - - -client = OAuth2CustomTimeout( - "CLIENT_ID", - "CLIENT_SECRET", - "AUTHORIZE_ENDPOINT", - "ACCESS_TOKEN_ENDPOINT", - refresh_token_endpoint="REFRESH_TOKEN_ENDPOINT", - revoke_token_endpoint="REVOKE_TOKEN_ENDPOINT", -) - - - - - - - - - - - - - - -
+ + + + +Reference - Clients¶ +Discord¶ + + + + + + + + + + + + + + + + + + + + + + + + + + DiscordOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Discord. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='discord') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'discord' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Facebook¶ + + + + + + + + httpx_oauth.clients.facebook + + +¶ + + + + + + + + + + + + + + + + + + + + FacebookOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Facebook. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='facebook') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'facebook' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + get_long_lived_access_token(token) + + + async + + +¶ + + + + + Request a long-lived access token +given a short-lived access token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The short-lived access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetLongLivedAccessTokenError + + + + An error occurred while requesting + + + + + + + +Examples: + long_lived_access_token = await client.get_long_lived_access_token("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +GitHub¶ + + + + + + + + httpx_oauth.clients.github + + +¶ + + + + + + + + + + + + + + + + + + + + GitHubOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[GitHubOAuth2AuthorizeParams] + + + OAuth2 client for GitHub. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='github') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'github' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. + +Tip +You should enable Email addresses permission +in the Permissions & events section of your GitHub app parameters. +You can find it at https://github.com/settings/apps/{YOUR_APP}/permissions. + + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + +Refresh tokens are not enabled by default +Refresh tokens are currently an optional feature you need to enable in your GitHub app parameters. +Read more. + + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Google¶ + + + + + + + + httpx_oauth.clients.google + + +¶ + + + + + + + + + + + + + + + + + + + + GoogleOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[GoogleOAuth2AuthorizeParams] + + + OAuth2 client for Google. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='google') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + + + + A unique name for the OAuth2 client. + + + + 'google' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Kakao¶ + + + + + + + + httpx_oauth.clients.kakao + + +¶ + + + + + + + + + + + + + + + + + + + + KakaoOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Kakao. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='kakao') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'kakao' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +LinkedIn¶ + + + + + + + + httpx_oauth.clients.linkedin + + +¶ + + + + + + + + + + + + + + + + + + + + LinkedInOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for LinkedIn. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='linkedin') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'linkedin' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + +Warning +Only available for selected partners. + + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Microsoft¶ + + + + + + + + httpx_oauth.clients.microsoft + + +¶ + + + + + + + + + + + + + + + + + + + + MicrosoftGraphOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Microsoft Graph API. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, tenant='common', scopes=BASE_SCOPES, name='microsoft') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + tenant + + str + + + + The tenant to use for the authorization URL. + + + + 'common' + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'microsoft' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, extras_params=None) + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Naver¶ + + + + + + + + httpx_oauth.clients.naver + + +¶ + + + + + + + + + + + + + + + + + + + + NaverOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Naver. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=BASE_SCOPES, name='naver') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'naver' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Okta¶ + + + + + + + + httpx_oauth.clients.okta + + +¶ + + + + + + + + + + + + + + + + + + + + OktaOAuth2 + + +¶ + + + + + Bases: OpenID + + + OAuth2 client for Okta. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, okta_domain, scopes=BASE_SCOPES, name='okta') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + okta_domain + + str + + + + The Okta organization domain. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'okta' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +OpenID¶ + + + + + + + + httpx_oauth.clients.openid + + +¶ + + + + + + + + + + + + + + + + + + + + OpenID + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + Generic client for providers following the OpenID Connect protocol. +Besides the Client ID and the Client Secret, you'll have to provide the OpenID configuration endpoint, allowing the client to discover the required endpoints automatically. By convention, it's usually served under the path .well-known/openid-configuration. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, openid_configuration_endpoint, name='openid', base_scopes=BASE_SCOPES) + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + openid_configuration_endpoint + + str + + + + OpenID Connect discovery endpoint URL. + + + + required + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'openid' + + + + base_scopes + + Optional[List[str]] + + + + The base scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + + + +Raises: + + + + Type + Description + + + + + + OpenIDConfigurationError + + + + An error occurred while fetching the OpenID configuration. + + + + + + + +Examples: + ```py +from httpx_oauth.clients.openid import OpenID +client = OpenID("CLIENT_ID", "CLIENT_SECRET", "https://example.fief.dev/.well-known/openid-configuration") +`` + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + OpenIDConfigurationError + + +¶ + + + + + Bases: OAuth2RequestError + + + Raised when an error occurred while fetching the OpenID configuration. + + + + + + + + + + + + + +Reddit¶ + + + + + + + + httpx_oauth.clients.reddit + + +¶ + + + + + + + + + + + + + + + + + + + + RedditOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[Dict[str, Any]] + + + OAuth2 client for Reddit. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, scopes=None, name='reddit') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + None + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'reddit' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + +Shopify¶ + + + + + + + + httpx_oauth.clients.shopify + + +¶ + + + + + + + + + + + + + + + + + + + + ShopifyOAuth2 + + +¶ + + + + + Bases: BaseOAuth2[ShopifyOAuth2AuthorizeParams] + + + OAuth2 client for Shopify. +The OAuth2 client for Shopify authenticates shop owners to allow making calls +to the Shopify Admin API. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, shop, scopes=BASE_SCOPES, api_version='2023-04', name='shopify') + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + shop + + str + + + + The shop subdomain. + + + + required + + + + scopes + + Optional[List[str]] + + + + The default scopes to be used in the authorization URL. + + + + BASE_SCOPES + + + + api_version + + str + + + + The version of the Shopify Admin API. + + + + '2023-04' + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'shopify' + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. + +get_id_email is based on the Shop resource +The implementation of get_id_email calls the Get Shop endpoint of the Shopify Admin API. +It means that it'll return you the ID of the shop and the email of the shop owner. + + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +Reference - Exceptions¶ + + + + + + + + + + + + + + + + + + + + + + + + + + GetIdEmailError + + +¶ + + + + + Bases: HTTPXOAuthError + + + Error raised while retrieving user profile from provider API. + + + + + + + + + + + + + + + + + + + + + + + + + + + + HTTPXOAuthError + + +¶ + + + + + Bases: Exception + + + Base exception class for every httpx-oauth errors. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +Reference - OAuth2¶ + + + + + + + + + + + + + + + + + + + + + + + + + OAuth2 = BaseOAuth2[Dict[str, Any]] + + + module-attribute + + +¶ + + + + + Generic OAuth2 client. + + +Examples: + from httpx_oauth.oauth2 import OAuth2 + +client = OAuth2( + "CLIENT_ID", + "CLIENT_SECRET", + "AUTHORIZE_ENDPOINT", + "ACCESS_TOKEN_ENDPOINT", + refresh_token_endpoint="REFRESH_TOKEN_ENDPOINT", + revoke_token_endpoint="REVOKE_TOKEN_ENDPOINT", +) + + + + + + + + + + + OAuth2ClientAuthMethod = Literal['client_secret_basic', 'client_secret_post'] + + + module-attribute + + +¶ + + + + + Supported OAuth2 client authentication methods. + + + + + + + + + + + BaseOAuth2 + + +¶ + + + + + Bases: Generic[T] + + + Base OAuth2 client. +This class provides a base implementation for OAuth2 clients. If you need to use a generic client, use OAuth2 instead. + + + + + + + + + + + + + + + + + + + __init__(client_id, client_secret, authorize_endpoint, access_token_endpoint, refresh_token_endpoint=None, revoke_token_endpoint=None, *, name='oauth2', base_scopes=None, token_endpoint_auth_method='client_secret_post', revocation_endpoint_auth_method=None) + +¶ + + + + + + +Parameters: + + + + Name + Type + Description + Default + + + + + client_id + + str + + + + The client ID provided by the OAuth2 provider. + + + + required + + + + client_secret + + str + + + + The client secret provided by the OAuth2 provider. + + + + required + + + + authorize_endpoint + + str + + + + The authorization endpoint URL. + + + + required + + + + access_token_endpoint + + str + + + + The access token endpoint URL. + + + + required + + + + refresh_token_endpoint + + Optional[str] + + + + The refresh token endpoint URL. + + + + None + + + + revoke_token_endpoint + + Optional[str] + + + + The revoke token endpoint URL. + + + + None + + + + name + + str + + + + A unique name for the OAuth2 client. + + + + 'oauth2' + + + + base_scopes + + Optional[List[str]] + + + + The base scopes to be used in the authorization URL. + + + + None + + + + token_endpoint_auth_method + + OAuth2ClientAuthMethod + + + + The authentication method to be used in the token endpoint. + + + + 'client_secret_post' + + + + revocation_endpoint_auth_method + + Optional[OAuth2ClientAuthMethod] + + + + The authentication method to be used in the revocation endpoint. + + + + None + + + + + + +Raises: + + + + Type + Description + + + + + + NotSupportedAuthMethodError + + + + The provided authentication method is not supported. + + + + + + MissingRevokeTokenAuthMethodError + + + + The revocation endpoint auth method is missing. + + + + + + + + + + + + + + + get_access_token(code, redirect_uri, code_verifier=None) + + + async + + +¶ + + + + + Requests an access token using the authorization code obtained +after the user has authorized the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + code + + str + + + + The authorization code. + + + + required + + + + redirect_uri + + str + + + + The URL where the user was redirected after authorization. + + + + required + + + + code_verifier + + Optional[str] + + + + Optional code verifier used +in the PKCE flow. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetAccessTokenError + + + + An error occurred while getting the access token. + + + + + + + +Examples: + access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + + + + + + + + + + + get_authorization_url(redirect_uri, state=None, scope=None, code_challenge=None, code_challenge_method=None, extras_params=None) + + + async + + +¶ + + + + + Builds the authorization URL +where the user should be redirected to authorize the application. + + +Parameters: + + + + Name + Type + Description + Default + + + + + redirect_uri + + str + + + + The URL where the user will be redirected after authorization. + + + + required + + + + state + + Optional[str] + + + + An opaque value used by the client to maintain state + + + + None + + + + scope + + Optional[List[str]] + + + + The scopes to be requested. +If not provided, base_scopes will be used. + + + + None + + + + code_challenge + + Optional[str] + + + + Optional +PKCE code challenge. + + + + None + + + + code_challenge_method + + Optional[Literal['plain', 'S256']] + + + + Optional +PKCE code challenge +method. + + + + None + + + + extras_params + + Optional[T] + + + + Optional extra parameters specific to the service. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + str + + + + The authorization URL. + + + + + + + +Examples: + py +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +)py + + + + + + + + + + get_id_email(token) + + + async + + +¶ + + + + + Returns the id and the email (if available) of the authenticated user +from the API provider. +It assumes you have asked for the required scopes. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + The access token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + Tuple[str, Optional[str]] + + + + A tuple with the id and the email of the authenticated user. + + + + + + + +Raises: + + + + Type + Description + + + + + + GetIdEmailError + + + + An error occurred while getting the id and email. + + + + + + + +Examples: + user_id, user_email = await client.get_id_email("TOKEN") + + + + + + + + + + + refresh_token(refresh_token) + + + async + + +¶ + + + + + Requests a new access token using a refresh token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + refresh_token + + str + + + + The refresh token. + + + + required + + + + + + + Returns: + + + + Type + Description + + + + + + OAuth2Token + + + + An access token response dictionary. + + + + + + + +Raises: + + + + Type + Description + + + + + + RefreshTokenError + + + + An error occurred while refreshing the token. + + + + + + RefreshTokenNotSupportedError + + + + The provider does not support token refresh. + + + + + + + +Examples: + access_token = await client.refresh_token("REFRESH_TOKEN") + + + + + + + + + + + revoke_token(token, token_type_hint=None) + + + async + + +¶ + + + + + Revokes a token. + + +Parameters: + + + + Name + Type + Description + Default + + + + + token + + str + + + + A token or refresh token to revoke. + + + + required + + + + token_type_hint + + Optional[str] + + + + Optional hint for the service to help it determine +if it's a token or refresh token. +Usually either token or refresh_token. + + + + None + + + + + + + Returns: + + + + Type + Description + + + + + + None + + + + None + + + + + + + +Raises: + + + + Type + Description + + + + + + RevokeTokenError + + + + An error occurred while revoking the token. + + + + + + RevokeTokenNotSupportedError + + + + The provider does not support token revoke. + + + + + + + + + + + + + + + + + + + + + + + + GetAccessTokenError + + +¶ + + + + + Bases: OAuth2RequestError + + + Error raised when an error occurs while getting an access token. + + + + + + + + + + + + MissingRevokeTokenAuthMethodError + + +¶ + + + + + Bases: OAuth2Error + + + Error raised when the revocation endpoint auth method is missing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + NotSupportedAuthMethodError + + +¶ + + + + + Bases: OAuth2Error + + + Error raised when an unsupported authentication method is used. + + + + + + + + + + + + + + + + + + + + + + + + + + + + OAuth2Error + + +¶ + + + + + Bases: HTTPXOAuthError + + + Base exception class for OAuth2 client errors. + + + + + + + + + + + + OAuth2RequestError + + +¶ + + + + + Bases: OAuth2Error + + + Base exception class for OAuth2 request errors. + + + + + + + + + + + + + + + + + + + + + + + + + + + + OAuth2Token + + +¶ + + + + + Bases: Dict[str, Any] + + + Wrapper around a standard Dict[str, Any] that bears the response +of a successful token request. +Properties can vary greatly from a service to another but, usually, +you can get access token like this: + + +Examples: + access_token = token["access_token"] + + + + + + + + + + + + + + + + + + + + is_expired() + +¶ + + + + + Checks if the token is expired. + + + Returns: + + + + Type + Description + + + + + + bool + + + + True if the token is expired, False otherwise + + + + + + + + + + + + + + + + + + + + + + + + RefreshTokenError + + +¶ + + + + + Bases: OAuth2RequestError + + + Error raised when an error occurs while refreshing a token. + + + + + + + + + + + + RefreshTokenNotSupportedError + + +¶ + + + + + Bases: OAuth2Error + + + Error raised when trying to refresh a token +on a provider that does not support it. + + + + + + + + + + + + + + + + + + + + + + + + + + + + RevokeTokenError + + +¶ + + + + + Bases: OAuth2RequestError + + + Error raised when an error occurs while revoking a token. + + + + + + + + + + + + RevokeTokenNotSupportedError + + +¶ + + + + + Bases: OAuth2Error + + + Error raised when trying to revole a token +on a provider that does not support it. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +Usage¶ +Create a client¶ +A generic OAuth2 class is provided to adapt to any OAuth2-compliant service. You can instantiate it like this: +from httpx_oauth.oauth2 import OAuth2 + +client = OAuth2( + "CLIENT_ID", + "CLIENT_SECRET", + "AUTHORIZE_ENDPOINT", + "ACCESS_TOKEN_ENDPOINT", + refresh_token_endpoint="REFRESH_TOKEN_ENDPOINT", + revoke_token_endpoint="REVOKE_TOKEN_ENDPOINT", +) + +Note that refresh_token_endpoint and revoke_token_endpoint are optional since not every services propose to refresh and revoke tokens. +Generate an authorization URL¶ +Use the get_authorization_url method to generate the authorization URL where you should redirect the user to ask for their approval. +authorization_url = await client.get_authorization_url( + "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"], +) + +Request an access token¶ +Once you have the authorization code, use the get_access_token method to exchange it with a valid access token. +It returns an OAuth2Token dictionary-like object. +access_token = await client.get_access_token("CODE", "https://www.tintagel.bt/oauth-callback") + +Refresh an access token¶ +For providers supporting it, you can ask for a fresh access token given a refresh token. For this, use the refresh_token method. +It returns an OAuth2Token dictionary-like object. +access_token = await client.refresh_token("REFRESH_TOKEN") + +Revoke an access or refresh token¶ +For providers supporting it, you can ask to revoke an access or refresh token. For this, use the revoke_token method. +Get authenticated user ID and email¶ +For convenience, we provide a method that'll use a valid access token to query the provider API and get the ID and the email (if available) of the authenticated user. For this, use the get_id_email method. +This method is implemented specifically on each provider. +Provided clients¶ +Out-of-the box, we support lot of popular providers like Google or Facebook, for which we provided dedicated classes with pre-configured endpoints. +Clients reference +Customize HTTPX client¶ +By default, requests are made using httpx.AsyncClient with default parameters. If you wish to customize settings, like setting timeout or proxies, you can do this by overloading the get_httpx_client method. +from typing import AsyncContextManager + +import httpx +from httpx_oauth.oauth2 import OAuth2 + + +class OAuth2CustomTimeout(OAuth2): + def get_httpx_client(self) -> AsyncContextManager[httpx.AsyncClient]: + return httpx.AsyncClient(timeout=10.0) # Use a default 10s timeout everywhere. + + +client = OAuth2CustomTimeout( + "CLIENT_ID", + "CLIENT_SECRET", + "AUTHORIZE_ENDPOINT", + "ACCESS_TOKEN_ENDPOINT", + refresh_token_endpoint="REFRESH_TOKEN_ENDPOINT", + revoke_token_endpoint="REVOKE_TOKEN_ENDPOINT", +) + + + + + + + + + + + + + + +