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. If not supported, set it to None.	None
revoke_token_endpoint	Optional[str]	The revoke token endpoint URL. If not supported, set it to None.	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. If the revocation endpoint is not supported, set it to None.	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 between the request and the callback.	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.