Authentication¶

prawcore separates authentication into two responsibilities:

Authenticators identify your registered Reddit application.
Authorizers use an authenticator to obtain and refresh the OAuth2 access tokens that authorize individual requests.

Authenticators¶

class prawcore.auth.BaseAuthenticator(requestor, client_id, redirect_uri=None)¶

Provide the base authenticator object that stores OAuth2 credentials.

Parameters:

requestor (Requestor)
client_id (str)
redirect_uri (str | None)

authorize_url(duration, scopes, state, implicit=False)¶

Return the URL used out-of-band to grant access to your application.

Parameters:

duration (str) – Either "permanent" or "temporary". "temporary" authorizations generate access tokens that last only 1 hour. "permanent" authorizations additionally generate a refresh token that can be indefinitely used to generate new hour-long access tokens. Only "temporary" can be specified if implicit is set to True.
scopes (list[str]) – A list of OAuth scopes to request authorization for.
state (str) – A string that will be reflected in the callback to redirect_uri. Elements must be printable ASCII characters in the range 0x20 through 0x7E inclusive. This value should be temporarily unique to the client for whom the URL was generated.
implicit (bool) – Use the implicit grant flow (default: False). This flow is only available for UntrustedAuthenticator instances.

Return type:

str

Returns:

URL to be used out-of-band for granting access to your application.

Raises:

InvalidInvocation if redirect_uri is not provided, if implicit is True and an authenticator other than UntrustedAuthenticator is used, or implicit is True and duration is "permanent".

property requestor: Requestor¶: Return the Requestor used to issue HTTP requests.

revoke_token(token, token_type=None)¶

Ask Reddit to revoke the provided token.

Parameters:

token (str) – The access or refresh token to revoke.
token_type (str | None) – When provided, hint to Reddit what the token type is for a possible efficiency gain. The value can be either "access_token" or "refresh_token".

Return type:

None

class prawcore.auth.TrustedAuthenticator(requestor, client_id, client_secret, redirect_uri=None)¶

Store OAuth2 authentication credentials for web, or script type apps.

Parameters:

requestor (Requestor)
client_id (str)
client_secret (str)
redirect_uri (str | None)

authorize_url(duration, scopes, state, implicit=False)¶

Return the URL used out-of-band to grant access to your application.

Parameters:

duration (str) – Either "permanent" or "temporary". "temporary" authorizations generate access tokens that last only 1 hour. "permanent" authorizations additionally generate a refresh token that can be indefinitely used to generate new hour-long access tokens. Only "temporary" can be specified if implicit is set to True.
scopes (list[str]) – A list of OAuth scopes to request authorization for.
state (str) – A string that will be reflected in the callback to redirect_uri. Elements must be printable ASCII characters in the range 0x20 through 0x7E inclusive. This value should be temporarily unique to the client for whom the URL was generated.
implicit (bool) – Use the implicit grant flow (default: False). This flow is only available for UntrustedAuthenticator instances.

Return type:

str

Returns:

URL to be used out-of-band for granting access to your application.

Raises:

property requestor: Requestor¶: Return the Requestor used to issue HTTP requests.

revoke_token(token, token_type=None)¶

Ask Reddit to revoke the provided token.

Parameters:

token (str) – The access or refresh token to revoke.
token_type (str | None) – When provided, hint to Reddit what the token type is for a possible efficiency gain. The value can be either "access_token" or "refresh_token".

Return type:

None

class prawcore.auth.UntrustedAuthenticator(requestor, client_id, redirect_uri=None)¶

Store OAuth2 authentication credentials for installed applications.

Parameters:

requestor (Requestor)
client_id (str)
redirect_uri (str | None)

authorize_url(duration, scopes, state, implicit=False)¶

Return the URL used out-of-band to grant access to your application.

Parameters:

duration (str) – Either "permanent" or "temporary". "temporary" authorizations generate access tokens that last only 1 hour. "permanent" authorizations additionally generate a refresh token that can be indefinitely used to generate new hour-long access tokens. Only "temporary" can be specified if implicit is set to True.
scopes (list[str]) – A list of OAuth scopes to request authorization for.
state (str) – A string that will be reflected in the callback to redirect_uri. Elements must be printable ASCII characters in the range 0x20 through 0x7E inclusive. This value should be temporarily unique to the client for whom the URL was generated.
implicit (bool) – Use the implicit grant flow (default: False). This flow is only available for UntrustedAuthenticator instances.

Return type:

str

Returns:

URL to be used out-of-band for granting access to your application.

Raises:

property requestor: Requestor¶: Return the Requestor used to issue HTTP requests.

revoke_token(token, token_type=None)¶

Ask Reddit to revoke the provided token.

Parameters:

token (str) – The access or refresh token to revoke.
token_type (str | None) – When provided, hint to Reddit what the token type is for a possible efficiency gain. The value can be either "access_token" or "refresh_token".

Return type:

None

Authorizers¶

class prawcore.auth.BaseAuthorizer(authenticator)¶

Superclass for OAuth2 authorization tokens and scopes.

Parameters:: authenticator (BaseAuthenticator)

AUTHENTICATOR_CLASS¶: alias of BaseAuthenticator

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

revoke()¶

Revoke the current Authorization.

Return type:: None

class prawcore.auth.Authorizer(authenticator, *, post_refresh_callback=None, pre_refresh_callback=None, refresh_token=None)¶

Manages OAuth2 authorization tokens and scopes.

Parameters:

authenticator (BaseAuthenticator)
post_refresh_callback (Callable[[Authorizer], None] | None)
pre_refresh_callback (Callable[[Authorizer], None] | None)
refresh_token (str | None)

AUTHENTICATOR_CLASS¶: alias of BaseAuthenticator

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

authorize(code)¶

Obtain and set authorization tokens based on code.

Parameters:: code (str) – The code obtained by an out-of-band authorization request to Reddit.
Return type:: None

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

refresh()¶

Obtain a new access token from the refresh_token.

Return type:: None

revoke(only_access=False)¶

Revoke the current Authorization.

Parameters:: only_access (bool) – When explicitly set to True, do not evict the refresh token if one is set.
Return type:: None

Revoking a refresh token will in-turn revoke all access tokens associated with that authorization.

class prawcore.auth.DeviceIDAuthorizer(authenticator, device_id=None, scopes=None)¶

Manages app-only OAuth2 for ‘installed’ applications.

While the "*" scope will be available, some endpoints simply will not work due to the lack of an associated Reddit account.

Parameters:

authenticator (BaseAuthenticator)
device_id (str | None)
scopes (list[str] | None)

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

refresh()¶

Obtain a new access token.

Return type:: None

revoke()¶

Revoke the current Authorization.

Return type:: None

class prawcore.auth.ImplicitAuthorizer(authenticator, access_token, expires_in, scope)¶

Manages implicit installed-app type authorizations.

Parameters:

authenticator (UntrustedAuthenticator)
access_token (str)
expires_in (int)
scope (str)

AUTHENTICATOR_CLASS¶: alias of UntrustedAuthenticator

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

revoke()¶

Revoke the current Authorization.

Return type:: None

class prawcore.auth.ReadOnlyAuthorizer(authenticator, scopes=None)¶

Manages authorizations that are not associated with a Reddit account.

While the "*" scope will be available, some endpoints simply will not work due to the lack of an associated Reddit account.

Parameters:

authenticator (BaseAuthenticator)
scopes (list[str] | None)

AUTHENTICATOR_CLASS¶: alias of TrustedAuthenticator

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

authorize(code)¶

Obtain and set authorization tokens based on code.

Parameters:: code (str) – The code obtained by an out-of-band authorization request to Reddit.
Return type:: None

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

refresh()¶

Obtain a new ReadOnly access token.

Return type:: None

revoke(only_access=False)¶

Revoke the current Authorization.

Parameters:: only_access (bool) – When explicitly set to True, do not evict the refresh token if one is set.
Return type:: None

Revoking a refresh token will in-turn revoke all access tokens associated with that authorization.

class prawcore.auth.ScriptAuthorizer(authenticator, username, password, two_factor_callback=None, scopes=None)¶

Manages personal-use script type authorizations.

Only users who are listed as developers for the application will be granted access tokens.

Parameters:

authenticator (BaseAuthenticator)
username (str | None)
password (str | None)
two_factor_callback (Callable[[], str] | None)
scopes (list[str] | None)

AUTHENTICATOR_CLASS¶: alias of TrustedAuthenticator

property authenticator: BaseAuthenticator¶: Return the BaseAuthenticator used to authenticate requests.

authorize(code)¶

Obtain and set authorization tokens based on code.

Parameters:: code (str) – The code obtained by an out-of-band authorization request to Reddit.
Return type:: None

is_valid()¶

Return whether the Authorizer is ready to authorize requests.

A True return value does not guarantee that the access_token is actually valid on the server side.

Return type:: bool

refresh()¶

Obtain a new personal-use script type access token.

Return type:: None

revoke(only_access=False)¶

Revoke the current Authorization.

Parameters:: only_access (bool) – When explicitly set to True, do not evict the refresh token if one is set.
Return type:: None

Revoking a refresh token will in-turn revoke all access tokens associated with that authorization.