Models¶

The models package contains several data models and exceptions that are internally used throughout the code. End-users shouldn’t have to deal with these classes, except for error handling.

Errors¶

All exceptions raised in the aiohttp-oauth2-client package inherit from the aiohttp_oauth2_client.models.errors.AuthError exception. This can be useful for catching auth errors in your code.

exception aiohttp_oauth2_client.models.errors.AuthError[source]¶

Bases: Exception

Auth error.

exception aiohttp_oauth2_client.models.errors.OAuth2Error(response: ErrorResponse)[source]¶

Bases: AuthError

Error in the OAuth 2.0 authorization process.

Parameters:: response (ErrorResponse) –

Grant types¶

class aiohttp_oauth2_client.models.grant.GrantType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: str, Enum

Enumeration of OAuth 2.0 grant types with their corresponding identifier.

AUTHORIZATION_CODE = 'authorization_code'¶

CLIENT_CREDENTIALS = 'client_credentials'¶

DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code'¶

REFRESH_TOKEN = 'refresh_token'¶

RESOURCE_OWNER_PASSWORD_CREDENTIALS = 'password'¶

Proof Key for Code Exchange (PKCE)¶

class aiohttp_oauth2_client.models.pkce.PKCE[source]¶

Bases: object

Proof Key for Code Exchange by OAuth Public Clients

Generates code verifier and code challenge.

https://datatracker.ietf.org/doc/html/rfc7636

Variables:

code_verifier – code verifier
code_challenge_method – code challenge method, always is S256
code_challenge – code challenge

static create_code_challenge(code_verifier: bytes) → bytes[source]¶

Create a code challenge based on the code verifier.

Parameters:: code_verifier (bytes) – code verifier
Returns:: code challenge as a byte string
Return type:: bytes

static create_code_verifier() → bytes[source]¶

Create a random code verifier.

Returns:: code verifier as a byte string
Return type:: bytes

Request¶

pydantic model aiohttp_oauth2_client.models.request.AccessTokenRequest[source]¶

Bases: BaseModel

Base model for OAuth 2.0 access token request.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "AccessTokenRequest",
   "description": "Base model for OAuth 2.0 access token request.",
   "type": "object",
   "properties": {
      "grant_type": {
         "title": "Grant Type",
         "type": "string"
      }
   },
   "additionalProperties": true,
   "required": [
      "grant_type"
   ]
}

Config:

extra: str = allow

Fields:

grant_type (str)

field grant_type: str [Required]¶: OAuth 2.0 grant type

pydantic model aiohttp_oauth2_client.models.request.AuthorizationCodeAccessTokenRequest[source]¶

Bases: AccessTokenRequest

Request model for the access token request with the Authorization Code grant.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "AuthorizationCodeAccessTokenRequest",
   "description": "Request model for the access token request with the Authorization Code grant.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3",
   "type": "object",
   "properties": {
      "grant_type": {
         "default": "authorization_code",
         "title": "Grant Type",
         "type": "string"
      },
      "code": {
         "title": "Code",
         "type": "string"
      },
      "redirect_uri": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Redirect Uri"
      },
      "client_id": {
         "title": "Client Id",
         "type": "string"
      }
   },
   "additionalProperties": true,
   "required": [
      "code",
      "client_id"
   ]
}

Config:

extra: str = allow

Fields:

client_id (str)
code (str)
grant_type (str)
redirect_uri (str | None)

field client_id: str [Required]¶: Client identifier

field code: str [Required]¶: Authorization code received from the authorization server

field grant_type: str = GrantType.AUTHORIZATION_CODE¶: OAuth 2.0 grant type

field redirect_uri: str | None = None¶: Redirect URI

pydantic model aiohttp_oauth2_client.models.request.AuthorizationRequest[source]¶

Bases: BaseModel

The Authorization Request model.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "AuthorizationRequest",
   "description": "The Authorization Request model.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1",
   "type": "object",
   "properties": {
      "response_type": {
         "default": "code",
         "title": "Response Type",
         "type": "string"
      },
      "client_id": {
         "title": "Client Id",
         "type": "string"
      },
      "redirect_uri": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Redirect Uri"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      },
      "state": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "State"
      }
   },
   "required": [
      "client_id"
   ]
}

Fields:

client_id (str)
redirect_uri (str | None)
response_type (str)
scope (str | None)
state (str | None)

field client_id: str [Required]¶: Client identifier

field redirect_uri: str | None = None¶: Redirect URI

field response_type: str = 'code'¶

field scope: str | None = None¶: Scope of the access request

field state: str | None = None¶: Opaque value used by the client to maintain state between the request and callback

pydantic model aiohttp_oauth2_client.models.request.AuthorizationRequestPKCE[source]¶

Bases: AuthorizationRequest

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "AuthorizationRequestPKCE",
   "type": "object",
   "properties": {
      "response_type": {
         "default": "code",
         "title": "Response Type",
         "type": "string"
      },
      "client_id": {
         "title": "Client Id",
         "type": "string"
      },
      "redirect_uri": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Redirect Uri"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      },
      "state": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "State"
      },
      "code_challenge": {
         "title": "Code Challenge",
         "type": "string"
      },
      "code_challenge_method": {
         "title": "Code Challenge Method",
         "type": "string"
      }
   },
   "required": [
      "client_id",
      "code_challenge",
      "code_challenge_method"
   ]
}

Fields:

code_challenge (str)
code_challenge_method (str)

field code_challenge: str [Required]¶: Code challenge

field code_challenge_method: str [Required]¶: Code challenge method

pydantic model aiohttp_oauth2_client.models.request.ClientCredentialsAccessTokenRequest[source]¶

Bases: AccessTokenRequest

Request model for the access token request with the Client Credentials grant.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "ClientCredentialsAccessTokenRequest",
   "description": "Request model for the access token request with the Client Credentials grant.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2",
   "type": "object",
   "properties": {
      "grant_type": {
         "default": "client_credentials",
         "title": "Grant Type",
         "type": "string"
      },
      "client_id": {
         "title": "Client Id",
         "type": "string"
      },
      "client_secret": {
         "title": "Client Secret",
         "type": "string"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      }
   },
   "additionalProperties": true,
   "required": [
      "client_id",
      "client_secret"
   ]
}

Config:

extra: str = allow

Fields:

client_id (str)
client_secret (str)
grant_type (str)
scope (str | None)

field client_id: str [Required]¶: Client identifier

field client_secret: str [Required]¶: Client secret

field grant_type: str = GrantType.CLIENT_CREDENTIALS¶: OAuth 2.0 grant type

field scope: str | None = None¶: Scope of the access request

pydantic model aiohttp_oauth2_client.models.request.DeviceAccessTokenRequest[source]¶

Bases: AccessTokenRequest

The Device Access Token Request model.

https://datatracker.ietf.org/doc/html/rfc8628#section-3.4

Variables:

grant_type – The grant type. Value MUST be set to “urn:ietf:params:oauth:grant-type:device_code”.
device_code – The device verification code, “device_code” from the device authorization response.
client_id – The client identifier.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "DeviceAccessTokenRequest",
   "description": "The Device Access Token Request model.\n\nhttps://datatracker.ietf.org/doc/html/rfc8628#section-3.4\n\n:ivar grant_type: The grant type. Value MUST be set to \"urn:ietf:params:oauth:grant-type:device_code\".\n:ivar device_code: The device verification code, \"device_code\" from the device authorization response.\n:ivar client_id: The client identifier.",
   "type": "object",
   "properties": {
      "grant_type": {
         "default": "urn:ietf:params:oauth:grant-type:device_code",
         "title": "Grant Type",
         "type": "string"
      },
      "device_code": {
         "title": "Device Code",
         "type": "string"
      },
      "client_id": {
         "title": "Client Id",
         "type": "string"
      }
   },
   "additionalProperties": true,
   "required": [
      "device_code",
      "client_id"
   ]
}

Config:

extra: str = allow

Fields:

client_id (str)
device_code (str)
grant_type (str)

field client_id: str [Required]¶: Client identifier

field device_code: str [Required]¶: Device verification code

field grant_type: str = GrantType.DEVICE_CODE¶: OAuth 2.0 grant type

pydantic model aiohttp_oauth2_client.models.request.DeviceAuthorizationRequest[source]¶

Bases: BaseModel

The Device Authorization Request model.

https://datatracker.ietf.org/doc/html/rfc8628#section-3.1

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "DeviceAuthorizationRequest",
   "description": "The Device Authorization Request model.\n\nhttps://datatracker.ietf.org/doc/html/rfc8628#section-3.1",
   "type": "object",
   "properties": {
      "client_id": {
         "title": "Client Id",
         "type": "string"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      }
   },
   "required": [
      "client_id"
   ]
}

Fields:

client_id (str)
scope (str | None)

field client_id: str [Required]¶: Client identifier

field scope: str | None = None¶: Scope of the access request

pydantic model aiohttp_oauth2_client.models.request.DeviceAuthorizationRequestPKCE[source]¶

Bases: DeviceAuthorizationRequest

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "DeviceAuthorizationRequestPKCE",
   "type": "object",
   "properties": {
      "client_id": {
         "title": "Client Id",
         "type": "string"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      },
      "code_challenge": {
         "title": "Code Challenge",
         "type": "string"
      },
      "code_challenge_method": {
         "title": "Code Challenge Method",
         "type": "string"
      }
   },
   "required": [
      "client_id",
      "code_challenge",
      "code_challenge_method"
   ]
}

Fields:

code_challenge (str)
code_challenge_method (str)

field code_challenge: str [Required]¶: Code challenge

field code_challenge_method: str [Required]¶: Code challenge method

pydantic model aiohttp_oauth2_client.models.request.RefreshTokenAccessTokenRequest[source]¶

Bases: AccessTokenRequest

Request model for the access token request using a Refresh Token.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "RefreshTokenAccessTokenRequest",
   "description": "Request model for the access token request using a Refresh Token.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-6",
   "type": "object",
   "properties": {
      "grant_type": {
         "default": "refresh_token",
         "title": "Grant Type",
         "type": "string"
      },
      "refresh_token": {
         "title": "Refresh Token",
         "type": "string"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      }
   },
   "additionalProperties": true,
   "required": [
      "refresh_token"
   ]
}

Config:

extra: str = allow

Fields:

grant_type (str)
refresh_token (str)
scope (str | None)

field grant_type: str = GrantType.REFRESH_TOKEN¶: OAuth 2.0 grant type

field refresh_token: str [Required]¶: Refresh token

field scope: str | None = None¶: Scope of the access request

pydantic model aiohttp_oauth2_client.models.request.ResourceOwnerPasswordCredentialsAccessTokenRequest[source]¶

Bases: AccessTokenRequest

Request model for the access token request with the Resource Owner Password Credentials grant.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "ResourceOwnerPasswordCredentialsAccessTokenRequest",
   "description": "Request model for the access token request with the Resource Owner Password Credentials grant.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-4.3.2",
   "type": "object",
   "properties": {
      "grant_type": {
         "default": "password",
         "title": "Grant Type",
         "type": "string"
      },
      "username": {
         "title": "Username",
         "type": "string"
      },
      "password": {
         "title": "Password",
         "type": "string"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      }
   },
   "additionalProperties": true,
   "required": [
      "username",
      "password"
   ]
}

Config:

extra: str = allow

Fields:

grant_type (str)
password (str)
scope (str | None)
username (str)

field grant_type: str = GrantType.RESOURCE_OWNER_PASSWORD_CREDENTIALS¶: OAuth 2.0 grant type

field password: str [Required]¶: Resource owner password

field scope: str | None = None¶: Scope of the access request

field username: str [Required]¶: Resource owner username

Response¶

pydantic model aiohttp_oauth2_client.models.response.AuthorizationResponse[source]¶

Bases: BaseModel

The Authorization Response model.

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

Variables:

code – The authorization code generated by the authorization server.
state – State

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "AuthorizationResponse",
   "description": "The Authorization Response model.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2\n\n:ivar code: The authorization code generated by the authorization server.\n:ivar state: State",
   "type": "object",
   "properties": {
      "code": {
         "title": "Code",
         "type": "string"
      },
      "state": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "State"
      }
   },
   "required": [
      "code"
   ]
}

Fields:

code (str)
state (str | None)

field code: str [Required]¶: Authorization code generated by the authorization server

field state: str | None = None¶: State parameter from the client authorization request, if it was present

pydantic model aiohttp_oauth2_client.models.response.DeviceAuthorizationResponse[source]¶

Bases: BaseModel

The Device Authorization Response model.

https://datatracker.ietf.org/doc/html/rfc8628#section-3.2

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "DeviceAuthorizationResponse",
   "description": "The Device Authorization Response model.\n\nhttps://datatracker.ietf.org/doc/html/rfc8628#section-3.2",
   "type": "object",
   "properties": {
      "device_code": {
         "title": "Device Code",
         "type": "string"
      },
      "user_code": {
         "title": "User Code",
         "type": "string"
      },
      "verification_uri": {
         "title": "Verification Uri",
         "type": "string"
      },
      "verification_uri_complete": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Verification Uri Complete"
      },
      "expires_in": {
         "title": "Expires In",
         "type": "integer"
      },
      "interval": {
         "default": 5,
         "title": "Interval",
         "type": "integer"
      }
   },
   "required": [
      "device_code",
      "user_code",
      "verification_uri",
      "expires_in"
   ]
}

Fields:

device_code (str)
expires_in (int)
interval (int)
user_code (str)
verification_uri (str)
verification_uri_complete (str | None)

field device_code: str [Required]¶: Device verification code

field expires_in: int [Required]¶: Lifetime in seconds of the “device_code” and “user_code”.

field interval: int = 5¶: Minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint.

field user_code: str [Required]¶: End-user verification code

field verification_uri: str [Required]¶: End-user verification URI on the authorization server

field verification_uri_complete: str | None = None¶: Verification URI that includes the “user_code” which is designed for non-textual transmission.

pydantic model aiohttp_oauth2_client.models.response.ErrorResponse[source]¶

Bases: BaseModel

OAuth2 Error Response model.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "ErrorResponse",
   "description": "OAuth2 Error Response model.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-5.2",
   "type": "object",
   "properties": {
      "error": {
         "title": "Error",
         "type": "string"
      },
      "error_description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Error Description"
      },
      "error_uri": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Error Uri"
      }
   },
   "required": [
      "error"
   ]
}

Fields:

error (str)
error_description (str | None)
error_uri (str | None)

field error: str [Required]¶: A single ASCII error code

field error_description: str | None = None¶: Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred.

field error_uri: str | None = None¶: A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

Token¶

pydantic model aiohttp_oauth2_client.models.token.Token[source]¶

Bases: BaseModel

Token Response model.

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

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "title": "Token",
   "description": "Token Response model.\n\nhttps://datatracker.ietf.org/doc/html/rfc6749#section-5.1",
   "type": "object",
   "properties": {
      "access_token": {
         "title": "Access Token",
         "type": "string"
      },
      "token_type": {
         "title": "Token Type",
         "type": "string"
      },
      "expires_in": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Expires In"
      },
      "refresh_token": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Refresh Token"
      },
      "scope": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Scope"
      },
      "expires_at": {
         "title": "Expires At",
         "type": "integer"
      }
   },
   "additionalProperties": true,
   "required": [
      "access_token",
      "token_type",
      "expires_at"
   ]
}

Config:

extra: str = allow

Fields:

access_token (str)
expires_at (int)
expires_in (int | None)
refresh_token (str | None)
scope (str | None)
token_type (str)

Validators:

_validate_expires_at » all fields

field access_token: str [Required]¶: Access token issued by the authorization server

field expires_at: int [Required]¶: Expiration time of the access token

field expires_in: int | None = None¶: Lifetime in seconds of the access token

field refresh_token: str | None = None¶: Refresh token, which can be used to obtain new access tokens

field scope: str | None = None¶: Scope of the access token

field token_type: str [Required]¶: Type of the token issued

is_expired(early_expiry: int = 30) → bool[source]¶

Indicates whether the access token is expired. The early expiry parameter allows to have some margin on the token expiry time.

Parameters:: early_expiry (int) – early expiry in seconds
Returns:: True if the access token is valid given the early expiry, False otherwise
Return type:: bool