Client API References

This part of the documentation covers the interface of Authlib Client.

Requests OAuth Sessions

class authlib.integrations.requests_client.OAuth1Session(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)

create_authorization_url(url, request_token=None, **kwargs)

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters:

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns:

The authorization URL with new parameters embedded.

fetch_access_token(url, verifier=None, **kwargs)

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters:

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns:

A token dict.

fetch_request_token(url, **kwargs)

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters:

• url – Request Token endpoint.

• kwargs – Extra parameters to include for fetching token.

Returns:

A Request Token dict.

parse_authorization_response(url)

Extract parameters from the post authorization redirect response URL.

Parameters:

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns:

A dict of parameters extracted from the URL.

class authlib.integrations.requests_client.OAuth1Auth(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', realm=None, force_include_body=False)

Signs the request using OAuth 1 (RFC5849)

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, 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.

• 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

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, 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, **kwargs)

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

HTTPX OAuth Clients

class authlib.integrations.httpx_client.OAuth1Auth(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', realm=None, force_include_body=False)

Signs the httpx request using OAuth 1 (RFC5849)

auth_flow(request: Request) → Generator[Request, Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

class authlib.integrations.httpx_client.OAuth1Client(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)

create_authorization_url(url, request_token=None, **kwargs)

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters:

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns:

The authorization URL with new parameters embedded.

fetch_access_token(url, verifier=None, **kwargs)

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters:

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns:

A token dict.

fetch_request_token(url, **kwargs)

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters:

• url – Request Token endpoint.

• kwargs – Extra parameters to include for fetching token.

Returns:

A Request Token dict.

parse_authorization_response(url)

Extract parameters from the post authorization redirect response URL.

Parameters:

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns:

A dict of parameters extracted from the URL.

class authlib.integrations.httpx_client.AsyncOAuth1Client(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)

create_authorization_url(url, request_token=None, **kwargs)

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters:

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns:

The authorization URL with new parameters embedded.

async fetch_access_token(url, verifier=None, **kwargs)

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters:

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns:

A token dict.

fetch_request_token(url, **kwargs)

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters:

• url – Request Token endpoint.

• kwargs – Extra parameters to include for fetching token.

Returns:

A Request Token dict.

parse_authorization_response(url)

Extract parameters from the post authorization redirect response URL.

Parameters:

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns:

A dict of parameters extracted from the URL.

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

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, 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, **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

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

Flask Registry and RemoteApp

class authlib.integrations.flask_client.OAuth(app=None, cache=None, fetch_token=None, update_token=None)

create_client(name)

Create or get the given named OAuth client. For instance, the OAuth registry has .register a twitter client, developers may access the client with:

client = oauth.create_client('twitter')

Param:

name: Name of the remote application

Returns:

OAuth remote app

init_app(app, cache=None, fetch_token=None, update_token=None)

Initialize lazy for Flask app. This is usually used for Flask application factory pattern.

register(name, overwrite=False, **kwargs)

Registers a new remote application.

Parameters:

• name – Name of the remote application.

• overwrite – Overwrite existing config with framework settings.

• kwargs – Parameters for RemoteApp.

Find parameters for the given remote app class. When a remote app is registered, it can be accessed with named attribute:

oauth.register('twitter', client_id='', ...)
oauth.twitter.get('timeline')

Django Registry and RemoteApp

class authlib.integrations.django_client.OAuth(cache=None, fetch_token=None, update_token=None)

create_client(name)

Create or get the given named OAuth client. For instance, the OAuth registry has .register a twitter client, developers may access the client with:

client = oauth.create_client('twitter')

Param:

name: Name of the remote application

Returns:

OAuth remote app

register(name, overwrite=False, **kwargs)

Registers a new remote application.

Parameters:

• name – Name of the remote application.

• overwrite – Overwrite existing config with framework settings.

• kwargs – Parameters for RemoteApp.

Find parameters for the given remote app class. When a remote app is registered, it can be accessed with named attribute:

oauth.register('twitter', client_id='', ...)
oauth.twitter.get('timeline')

Starlette Registry and RemoteApp

class authlib.integrations.starlette_client.OAuth(config=None, cache=None, fetch_token=None, update_token=None)

create_client(name)

Create or get the given named OAuth client. For instance, the OAuth registry has .register a twitter client, developers may access the client with:

client = oauth.create_client('twitter')

Param:

name: Name of the remote application

Returns:

OAuth remote app

register(name, overwrite=False, **kwargs)

Registers a new remote application.

Parameters:

• name – Name of the remote application.

• overwrite – Overwrite existing config with framework settings.

• kwargs – Parameters for RemoteApp.

Find parameters for the given remote app class. When a remote app is registered, it can be accessed with named attribute:

oauth.register('twitter', client_id='', ...)
oauth.twitter.get('timeline')