API Reference

This page provides a breakdown of the starlette-discord OAuth2 API.

Discord OAuth2 Client

class starlette_discord.DiscordOAuthClient(client_id, client_secret, redirect_uri, scopes=('identify',))

Client for Discord Oauth2.

Parameters:

  • client_id (Union[str, int]) – Discord application client ID.

  • client_secret (str) – Discord application client secret.

  • redirect_uri (str) – Discord application redirect URI.

  • scopes (Tuple[str]) – Discord authorization scopes.

await login(code)

Shorthand for session setup + identify.

Parameters:

code (str) – The OAuth2 code provided by the authorization request.

Returns:

The user who authorized the application.

Return type:

User

await login_return_token(code)

Shorthand for session setup + identify. Returns user and token.

Parameters:

code (str) – The OAuth2 code provided by the authorization request.

Returns:

  • Tuple[user, token]

  • user (User) – The user who authorized the application.

  • token (Dict[str, Union[str, int, float]]) – The access token provided by the Discord API.

redirect(state=None, prompt=None, redirect_uri=None)

Returns a RedirectResponse that directs to Discord login.

Parameters:

  • state (Optional[str]) – Optional state parameter for Discord redirect URL. Docs can be found here.

  • prompt (Optional[str]) – Optional prompt parameter for Discord redirect URL. If consent, user is prompted to re-approve authorization. If none, skips authorization if user has already authorized. Defaults to consent.

  • redirect_uri (Optional[str]) – Optional redirect URI to pass to Discord. Defaults to the client’s redirect URI.

session(code) → DiscordOAuthSession

Create a new DiscordOAuthSession from an authorization code.

Parameters:

code (str) – The OAuth2 code provided by the Discord API.

Returns:

A new OAuth session.

Return type:

DiscordOAuthSession

session_from_token(token) → DiscordOAuthSession

Create a new DiscordOAuthSession from an existing token.

Parameters:

token (Dict[str, Union[str, int, float]]) – An existing (valid) access token to use instead of the OAuth code exchange.

Returns:

A new OAuth session.

Return type:

DiscordOAuthSession

Discord OAuth2 Session

class starlette_discord.DiscordOAuthSession(*args: Any, **kwargs: Any)

Session containing data for a single authorized user. Handles authorization internally.

Warning

It is recommended to not construct this class directly. Use DiscordOAuthClient.session or DiscordOAuthClient.session_from_token instead.

Note

Either the ‘code’ or ‘token’ parameter must be provided, but not both.

Parameters:

  • code (Optional[str]) – Authorization code included with user request after redirect from Discord.

  • token (Optional[Dict[str, Union[str, int, :class`float`]]]) – A previously generated, valid, access token to use instead of the OAuth code exchange

  • client_id (str) – Your Discord application client ID.

  • scope (str) – Discord authorization scopes separated by %20.

  • redirect_uri (str) – Your Discord application redirect URI.

  • code – Authorization code included with user request after redirect from Discord.

  • token – A previously generated, valid, access token to use instead of the OAuth code exchange

property cached_connections

The session’s cached account connections, if a connections() request has previously been made.

Type:

List[dict]

property cached_guilds

The session’s cached guilds, if a guilds() request has previously been made.

Type:

List[dict]

property cached_user

The session’s cached user, if an identify() request has previously been made.

Type:

dict

await connections()

Fetch a user’s linked 3rd-party accounts.

Returns:

The user’s connections.

Return type:

List[Connection]

await guilds()

Fetch a user’s guild list.

Returns:

The user’s guild list.

Return type:

List[Guild]

await identify()

Identify a user.

Returns:

The user who authorized the application.

Return type:

User

await join_guild(guild_id, bot_token, user_id=None)

Add a user to a guild.

Parameters:

  • guild_id (int) – The ID of the guild to add the user to.

  • bot_token (str) – Your bot’s token.

  • user_id (Optional[int]) – ID of the user, if known. If not specified, will first identify the user.

new_state()

Generate a new state string for verifying authorizations.

Returns:

The state string that was generated.

Return type:

str

await refresh_token(token_url, refresh_token=None, body='', auth=None, timeout=None, headers=None, verify_ssl=True, proxies=None, **kwargs)

Fetch a new access token using a refresh token. :param token_url: The token endpoint, must be HTTPS. :param refresh_token: The refresh_token to use. :param body: Optional application/x-www-form-urlencoded body to add the

include in the token request. Prefer kwargs over body.

Parameters:

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

  • timeout – Timeout of the request in seconds.

  • headers – A dict of headers to be used by requests.

  • verify – Verify SSL certificate.

  • proxies – The proxies argument will be passed to requests.

  • kwargs – Extra parameters to include in the token request.

Returns:

A token dict

property token

The session’s current OAuth token, if one exists.

Type:

Dict[str, Union[str, int, float]]