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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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 the long-lived access token.

Examples:

long_lived_access_token = await client.get_long_lived_access_token("TOKEN")

get_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

get_emails(token) async

Return the emails 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
list[dict[str, Any]]	A list of emails as described in the GitHub API.

Raises:

Type	Description
GetProfileError	An error occurred while getting the emails.

Examples:

emails = await client.get_emails("TOKEN")

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")

get_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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
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.

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	str	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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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_profile(token) async

Returns the profile 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
dict[str, Any]	The profile of the authenticated user.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile.

Examples:

profile = await client.get_profile("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 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:

authorization_url = await client.get_authorization_url(
    "https://www.tintagel.bt/oauth-callback", scope=["SCOPE1", "SCOPE2", "SCOPE3"],
)

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")

get_profile(token) async

Returns the profile of the authenticated user from the API provider.

get_profile is based on the Shop resource

The implementation of get_profile calls the Get Shop endpoint of the Shopify Admin API. It means that it'll return you the profile of the shop.

Parameters:

Name	Type	Description	Default
token	str	The access token.	required

Returns:

Type	Description
dict[str, Any]	The profile of the authenticated shop.

Raises:

Type	Description
GetProfileError	An error occurred while getting the profile

Examples:

profile = await client.get_profile("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.