Grants

The OAuth2Grant abstract class defines the high-level interface for OAuth 2.0 grant implementations. The grant object should be used as an async context manager.

Common

class aiohttp_oauth2_client.grant.common.OAuth2Grant(token_url: str | URL, token: dict | None = None, **kwargs)

Bases: object

Generic OAuth 2.0 Grant class.

Parameters:

• token_url (str | URL) – OAuth 2.0 Token URL

• token (dict | None) – OAuth 2.0 Token

• kwargs – extra arguments used in token request

async close()

Close the Grant object and its associated resources.

async ensure_active_token()

Ensure that the stored access token is still active. If this is not the case, the token will be refreshed.

async execute_token_request(data: AccessTokenRequest) → Token

Execute a token request with the provided data.

Parameters:

data (AccessTokenRequest) – token request data

Returns:

OAuth 2.0 Token

Raises:

• OAuth2Error – if the token request fails

• aiohttp.ClientResponseError – if the HTTP error cannot be parsed as an OAuth 2.0 error response

Return type:

Token

async fetch_token()

Fetch an OAuth 2.0 token from the token endpoint and store it for subsequent use.

async prepare_request(headers: Mapping[str, str] | Mapping[istr, str] | CIMultiDict | CIMultiDictProxy | Iterable[Tuple[str | istr, str]] | None)

Prepare the HTTP request by adding the OAuth 2.0 access token to the Authorization header.

Parameters:

headers (Mapping[str, str] | Mapping[istr, str] | CIMultiDict | CIMultiDictProxy | Iterable[Tuple[str | istr, str]] | None) – HTTP request headers

Returns:

updated HTTP request headers

async refresh_token()

Obtain a new access token using the refresh token grant and store it for subsequent use.

Authorization Code

class aiohttp_oauth2_client.grant.authorization_code.AuthorizationCodeGrant(token_url: str | URL, authorization_url: str | URL, client_id: str, token: dict | None = None, pkce: bool = False, _web_server_port: int | None = None, **kwargs)

Bases: OAuth2Grant

OAuth 2.0 Authorization Code grant.

Use a browser login to request an authorization code, which is then used to request an access token.

https://datatracker.ietf.org/doc/html/rfc6749#section-4.1

Parameters:

• token_url (str | URL) – OAuth 2.0 Token URL

• authorization_url (str | URL) – OAuth 2.0 Authorization URL

• client_id (str) – client identifier

• token (dict | None) – OAuth 2.0 Token

• pkce (bool) – use PKCE

• _web_server_port (int | None) – web server port for handling redirect callback, leave empty for random available port

timeout: int = 300

Client Credentials

class aiohttp_oauth2_client.grant.client_credentials.ClientCredentialsGrant(token_url: str | URL, client_id: str, client_secret: str, token: dict | None = None, **kwargs)

Bases: OAuth2Grant

OAuth 2.0 Client Credentials grant.

Use client credentials to obtain an access token.

https://datatracker.ietf.org/doc/html/rfc6749#section-4.4

Parameters:

• token_url (str | URL) – OAuth 2.0 Token URL

• client_id (str) – client identifier

• client_secret (str) – client secret

• token (dict | None) – OAuth 2.0 Token

async refresh_token()

Following the specification, the token response for the client credentials grant SHOULD NOT include a refresh token. The client credentials grant should be used to get a new access token when the previous one has expired.

https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.3

Some clients may issue a refresh token for the client credentials flow, even though it is not correct according to the specification. In this case, the refresh token will be used to obtain a new access token.

Resource Owner Password Credentials

class aiohttp_oauth2_client.grant.resource_owner_password_credentials.ResourceOwnerPasswordCredentialsGrant(token_url: str, username: str, password: str, token: dict | None = None, **kwargs)

Bases: OAuth2Grant

OAuth 2.0 Resource Owner Password Credentials grant.

Use the username and password of the resource owner to obatain an access token.

Parameters:

• token_url (str) – OAuth 2.0 Token URL

• username (str) – username of the resource owner

• password (str) – password of the resource owner

• token (dict | None) – OAuth 2.0 Token

Device Code

class aiohttp_oauth2_client.grant.device_code.DeviceCodeGrant(token_url: str | URL, device_authorization_url: str | URL, client_id: str, token: dict | None = None, pkce: bool = False, **kwargs)

Bases: OAuth2Grant

OAuth 2.0 Device Code grant.

Obtain user authorization on devices with limited input capabilities or lack a suitable browser to handle an interactive log in procedure. The user is instructed to review the authorization request on a secondary device, which does have the requisite input and browser capabilities to complete the user interaction.

Parameters:

• token_url (str | URL) – OAuth 2.0 Token URL

• device_authorization_url (str | URL) – OAuth 2.0 Device Authorization URL

• client_id (str) – client identifier

• token (dict | None) – OAuth 2.0 Token

• pkce (bool) – use PKCE