Reference

Requests OAuth 2.0

class authlib.integrations.requests_client.OAuth2Session(client_id=None, client_secret=None, token_endpoint_auth_method=None, revocation_endpoint_auth_method=None, scope=None, state=None, redirect_uri=None, token=None, token_placement='header', update_token=None, leeway=60, default_timeout=None, **kwargs)

Construct a new OAuth 2 client requests session.

Parameters:

  • client_id – Client ID, which you get from client registration.

  • client_secret – Client Secret, which you get from registration.

  • authorization_endpoint – URL of the authorization server’s authorization endpoint.

  • token_endpoint – URL of the authorization server’s token endpoint.

  • token_endpoint_auth_method – client authentication method for token endpoint.

  • revocation_endpoint – URL of the authorization server’s OAuth 2.0 revocation endpoint.

  • revocation_endpoint_auth_method – client authentication method for revocation endpoint.

  • scope – Scope that you needed to access user resources.

  • state – Shared secret to prevent CSRF attack.

  • redirect_uri – Redirect URI you registered as callback.

  • token – A dict of token attributes such as access_token, token_type and expires_at.

  • token_placement – The place to put token in HTTP request. Available values: “header”, “body”, “uri”.

  • update_token – A function for you to update token. It accept a OAuth2Token as parameter.

  • leeway – Time window in seconds before the actual expiration of the authentication token, that the token is considered expired and will be refreshed.

  • default_timeout – If settled, every requests will have a default timeout.

create_authorization_url(url, state=None, code_verifier=None, **kwargs)

Generate an authorization URL and state.

Parameters:

  • url – Authorization endpoint url, must be HTTPS.

  • state – An optional state string for CSRF protection. If not given it will be generated for you.

  • code_verifier – An optional code_verifier for code challenge.

  • kwargs – Extra parameters to include.

Returns:

authorization_url, state

fetch_token(url=None, body='', method='POST', headers=None, auth=None, grant_type=None, state=None, **kwargs)

Generic method for fetching an access token from the token endpoint.

Parameters:

  • url – Access Token endpoint URL, if not configured, authorization_response is used to extract token from its fragment (implicit way).

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • method – The HTTP method used to make the request. Defaults to POST, but may also be GET. Other methods should be added as needed.

  • headers – Dict to default request headers with.

  • auth – An auth tuple or method as accepted by requests.

  • grant_type – Use specified grant_type to fetch token.

  • state – Optional “state” value to fetch token.

Returns:

A OAuth2Token object (a dict too).

introspect_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Implementation of OAuth 2.0 Token Introspection defined via RFC7662.

Parameters:

  • url – Introspection Endpoint, must be HTTPS.

  • token – The token to be introspected.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Introspection Response

refresh_token(url=None, refresh_token=None, body='', auth=None, headers=None, **kwargs)

Fetch a new access token using a refresh token.

Parameters:

  • url – Refresh Token endpoint, must be HTTPS.

  • refresh_token – The refresh_token to use.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

A OAuth2Token object (a dict too).

register_client_auth_method(auth)

Extend client authenticate for token endpoint.

Parameters:

auth – an instance to sign the request

register_compliance_hook(hook_type, hook)

Register a hook for request/response tweaking.

Available hooks are:

  • access_token_response: invoked before token parsing.

  • refresh_token_request: invoked before refreshing token.

  • refresh_token_response: invoked before refresh token parsing.

  • protected_request: invoked before making a request.

  • revoke_token_request: invoked before revoking a token.

  • introspect_token_request: invoked before introspecting a token.

revoke_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Revoke token method defined via RFC7009.

Parameters:

  • url – Revoke Token endpoint, must be HTTPS.

  • token – The token to be revoked.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Revocation Response

class authlib.integrations.requests_client.OAuth2Auth(token, token_placement='header', client=None)

Sign requests for OAuth 2.0, currently only bearer token is supported.

class authlib.integrations.requests_client.AssertionSession(token_endpoint, issuer, subject, audience=None, grant_type=None, claims=None, token_placement='header', scope=None, default_timeout=None, leeway=60, **kwargs)

Constructs a new Assertion Framework for OAuth 2.0 Authorization Grants per RFC7521.

HTTPX OAuth 2.0

class authlib.integrations.httpx_client.OAuth2Auth(token, token_placement='header', client=None)

Sign requests for OAuth 2.0, currently only bearer token is supported.

class authlib.integrations.httpx_client.OAuth2Client(client_id=None, client_secret=None, token_endpoint_auth_method=None, revocation_endpoint_auth_method=None, scope=None, redirect_uri=None, token=None, token_placement='header', update_token=None, **kwargs)
create_authorization_url(url, state=None, code_verifier=None, **kwargs)

Generate an authorization URL and state.

Parameters:

  • url – Authorization endpoint url, must be HTTPS.

  • state – An optional state string for CSRF protection. If not given it will be generated for you.

  • code_verifier – An optional code_verifier for code challenge.

  • kwargs – Extra parameters to include.

Returns:

authorization_url, state

fetch_token(url=None, body='', method='POST', headers=None, auth=None, grant_type=None, state=None, **kwargs)

Generic method for fetching an access token from the token endpoint.

Parameters:

  • url – Access Token endpoint URL, if not configured, authorization_response is used to extract token from its fragment (implicit way).

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • method – The HTTP method used to make the request. Defaults to POST, but may also be GET. Other methods should be added as needed.

  • headers – Dict to default request headers with.

  • auth – An auth tuple or method as accepted by requests.

  • grant_type – Use specified grant_type to fetch token.

  • state – Optional “state” value to fetch token.

Returns:

A OAuth2Token object (a dict too).

introspect_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Implementation of OAuth 2.0 Token Introspection defined via RFC7662.

Parameters:

  • url – Introspection Endpoint, must be HTTPS.

  • token – The token to be introspected.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Introspection Response

refresh_token(url=None, refresh_token=None, body='', auth=None, headers=None, **kwargs)

Fetch a new access token using a refresh token.

Parameters:

  • url – Refresh Token endpoint, must be HTTPS.

  • refresh_token – The refresh_token to use.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

A OAuth2Token object (a dict too).

register_client_auth_method(auth)

Extend client authenticate for token endpoint.

Parameters:

auth – an instance to sign the request

register_compliance_hook(hook_type, hook)

Register a hook for request/response tweaking.

Available hooks are:

  • access_token_response: invoked before token parsing.

  • refresh_token_request: invoked before refreshing token.

  • refresh_token_response: invoked before refresh token parsing.

  • protected_request: invoked before making a request.

  • revoke_token_request: invoked before revoking a token.

  • introspect_token_request: invoked before introspecting a token.

revoke_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Revoke token method defined via RFC7009.

Parameters:

  • url – Revoke Token endpoint, must be HTTPS.

  • token – The token to be revoked.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Revocation Response

class authlib.integrations.httpx_client.AsyncOAuth2Client(client_id=None, client_secret=None, token_endpoint_auth_method=None, revocation_endpoint_auth_method=None, scope=None, redirect_uri=None, token=None, token_placement='header', update_token=None, leeway=60, **kwargs)
create_authorization_url(url, state=None, code_verifier=None, **kwargs)

Generate an authorization URL and state.

Parameters:

  • url – Authorization endpoint url, must be HTTPS.

  • state – An optional state string for CSRF protection. If not given it will be generated for you.

  • code_verifier – An optional code_verifier for code challenge.

  • kwargs – Extra parameters to include.

Returns:

authorization_url, state

fetch_token(url=None, body='', method='POST', headers=None, auth=None, grant_type=None, state=None, **kwargs)

Generic method for fetching an access token from the token endpoint.

Parameters:

  • url – Access Token endpoint URL, if not configured, authorization_response is used to extract token from its fragment (implicit way).

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • method – The HTTP method used to make the request. Defaults to POST, but may also be GET. Other methods should be added as needed.

  • headers – Dict to default request headers with.

  • auth – An auth tuple or method as accepted by requests.

  • grant_type – Use specified grant_type to fetch token.

  • state – Optional “state” value to fetch token.

Returns:

A OAuth2Token object (a dict too).

introspect_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Implementation of OAuth 2.0 Token Introspection defined via RFC7662.

Parameters:

  • url – Introspection Endpoint, must be HTTPS.

  • token – The token to be introspected.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Introspection Response

refresh_token(url=None, refresh_token=None, body='', auth=None, headers=None, **kwargs)

Fetch a new access token using a refresh token.

Parameters:

  • url – Refresh Token endpoint, must be HTTPS.

  • refresh_token – The refresh_token to use.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

A OAuth2Token object (a dict too).

register_client_auth_method(auth)

Extend client authenticate for token endpoint.

Parameters:

auth – an instance to sign the request

register_compliance_hook(hook_type, hook)

Register a hook for request/response tweaking.

Available hooks are:

  • access_token_response: invoked before token parsing.

  • refresh_token_request: invoked before refreshing token.

  • refresh_token_response: invoked before refresh token parsing.

  • protected_request: invoked before making a request.

  • revoke_token_request: invoked before revoking a token.

  • introspect_token_request: invoked before introspecting a token.

revoke_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)

Revoke token method defined via RFC7009.

Parameters:

  • url – Revoke Token endpoint, must be HTTPS.

  • token – The token to be revoked.

  • token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

  • body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

  • auth – An auth tuple or method as accepted by requests.

  • headers – Dict to default request headers with.

Returns:

Revocation Response

class authlib.integrations.httpx_client.AsyncAssertionClient(token_endpoint, issuer, subject, audience=None, grant_type=None, claims=None, token_placement='header', scope=None, **kwargs)