dropbox.oauth – OAuth

exception dropbox.oauth.BadRequestException

Bases: exceptions.Exception

Thrown if the redirect URL was missing parameters or if the given parameters were not valid.

The recommended action is to show an HTTP 400 error page.

exception dropbox.oauth.BadStateException

Bases: exceptions.Exception

Thrown if all the parameters are correct, but there’s no CSRF token in the session. This probably means that the session expired.

The recommended action is to redirect the user’s browser to try the approval process again.

exception dropbox.oauth.CsrfException

Bases: exceptions.Exception

Thrown if the given ‘state’ parameter doesn’t contain the CSRF token from the user’s session. This is blocked to prevent CSRF attacks.

The recommended action is to respond with an HTTP 403 error page.

class dropbox.oauth.DropboxOAuth2Flow(consumer_key, redirect_uri, session, csrf_token_session_key, consumer_secret=None, locale=None, token_access_type=None, scope=None, include_granted_scopes=None, use_pkce=False, timeout=100, ca_certs=None)

Bases: dropbox.oauth.DropboxOAuth2FlowBase

OAuth 2 authorization helper. Use this for web apps.

OAuth 2 has a two-step authorization process. The first step is having the user authorize your app. The second involves getting an OAuth 2 access token from Dropbox.

See examples under example/oauth

__init__(consumer_key, redirect_uri, session, csrf_token_session_key, consumer_secret=None, locale=None, token_access_type=None, scope=None, include_granted_scopes=None, use_pkce=False, timeout=100, ca_certs=None)

Construct an instance.

Parameters:
  • consumer_key (str) – Your API app’s “app key”.
  • redirect_uri (str) – The URI that the Dropbox server will redirect the user to after the user finishes authorizing your app. This URI must be HTTPS-based and pre-registered with the Dropbox servers, though localhost URIs are allowed without pre-registration and can be either HTTP or HTTPS.
  • session (dict) – A dict-like object that represents the current user’s web session (Will be used to save the CSRF token).
  • csrf_token_session_key (str) – The key to use when storing the CSRF token in the session (For example: “dropbox-auth-csrf-token”).
  • consumer_secret (str) – Your API app’s “app secret”.
  • locale (str) – The locale of the user of your application. For example “en” or “en_US”. Some API calls return localized data and error messages; this setting tells the server which locale to use. By default, the server uses “en_US”.
  • token_access_type (str) –

    The type of token to be requested. From the following enum:

    • None - creates a token with the app default (either legacy or online)
    • legacy - creates one long-lived token with no expiration
    • online - create one short-lived token with an expiration
    • offline - create one short-lived token with an expiration with a refresh token
  • scope (list) – List of scopes to request in base oauth flow. If left blank, will default to all scopes for app.
  • include_granted_scopes (str) –

    Which scopes to include from previous grants. From the following enum:

    • user - include user scopes in the grant
    • team - include team scopes in the grant
    • Note: If this user has never linked the app, include_granted_scopes must be None
  • use_pkce (bool) – Whether or not to use Sha256 based PKCE
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 100 seconds.
  • ca_cert (str) – path to CA certificate. If left blank, default certificate location will be used
finish(query_params)

Call this after the user has visited the authorize URL (see start()), approved your app and was redirected to your redirect URI.

Parameters:query_params (dict) – The query parameters on the GET request to your redirect URI.
Return type:class:OAuth2FlowResult
Raises:BadRequestException If the redirect URL was missing parameters or if the given parameters were not valid.
Raises:BadStateException If there’s no CSRF token in the session.
Raises:CsrfException If the state query parameter doesn’t contain the CSRF token from the user’s session.
Raises:NotApprovedException If the user chose not to approve your app.
Raises:ProviderException If Dropbox redirected to your redirect URI with some unexpected error identifier and error message.
start(url_state=None)

Starts the OAuth 2 authorization process.

This function builds an “authorization URL”. You should redirect your user’s browser to this
URL, which will give them an opportunity to grant your app access to their Dropbox account. When the user completes this process, they will be automatically redirected to the redirect_uri you passed in to the constructor. This function will also save a CSRF token to session[csrf_token_session_key] (as provided to the constructor). This CSRF token will be checked on finish() to prevent request forgery.
Parameters:url_state (str) – Any data that you would like to keep in the URL through the authorization process. This exact value will be returned to you by finish().
Returns:The URL for a page on Dropbox’s website. This page will let the user “approve” your app, which gives your app permission to access the user’s Dropbox account. Tell the user to visit this URL and approve your app.
class dropbox.oauth.DropboxOAuth2FlowNoRedirect(consumer_key, consumer_secret=None, locale=None, token_access_type=None, scope=None, include_granted_scopes=None, use_pkce=False, timeout=100, ca_certs=None)

Bases: dropbox.oauth.DropboxOAuth2FlowBase

OAuth 2 authorization helper for apps that can’t provide a redirect URI (such as the command-line example apps).

See examples under example/oauth

__init__(consumer_key, consumer_secret=None, locale=None, token_access_type=None, scope=None, include_granted_scopes=None, use_pkce=False, timeout=100, ca_certs=None)

Construct an instance.

Parameters:
  • consumer_key (str) – Your API app’s “app key”.
  • consumer_secret (str) – Your API app’s “app secret”.
  • locale (str) – The locale of the user of your application. For example “en” or “en_US”. Some API calls return localized data and error messages; this setting tells the server which locale to use. By default, the server uses “en_US”.
  • token_access_type (str) –

    the type of token to be requested. From the following enum:

    • None - creates a token with the app default (either legacy or online)
    • legacy - creates one long-lived token with no expiration
    • online - create one short-lived token with an expiration
    • offline - create one short-lived token with an expiration with a refresh token
  • scope (list) – list of scopes to request in base oauth flow. If left blank, will default to all scopes for app.
  • include_granted_scopes (str) –

    which scopes to include from previous grants. From the following enum:

    • user - include user scopes in the grant
    • team - include team scopes in the grant
    • Note: if this user has never linked the app, include_granted_scopes must be None
  • use_pkce (bool) – Whether or not to use Sha256 based PKCE. PKCE should be only use on client apps which doesn’t call your server. It is less secure than non-PKCE flow but can be used if you are unable to safely retrieve your app secret.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 100 seconds.
  • ca_cert (str) – path to CA certificate. If left blank, default certificate location will be used
finish(code)

If the user approves your app, they will be presented with an “authorization code”. Have the user copy/paste that authorization code into your app and then call this method to get an access token.

Parameters:code (str) – The authorization code shown to the user when they approved your app.
Return type:OAuth2FlowNoRedirectResult
Raises:The same exceptions as DropboxOAuth2Flow.finish().
start()

Starts the OAuth 2 authorization process.

Returns:The URL for a page on Dropbox’s website. This page will let the user “approve” your app, which gives your app permission to access the user’s Dropbox account. Tell the user to visit this URL and approve your app.
exception dropbox.oauth.NotApprovedException

Bases: exceptions.Exception

The user chose not to approve your app.

class dropbox.oauth.OAuth2FlowNoRedirectResult(access_token, account_id, user_id, refresh_token, expiration, scope)

Bases: object

Authorization information for an OAuth2Flow performed with no redirect.

__init__(access_token, account_id, user_id, refresh_token, expiration, scope)
Parameters:
  • access_token (str) – Token to be used to authenticate later requests.
  • account_id (str) – The Dropbox user’s account ID.
  • user_id (str) – Deprecated (use account_id instead).
  • refresh_token (str) – Token to be used to acquire new access token when existing one expires.
  • expiration (int or datetime) – Either the number of seconds from now that the token expires in or the datetime at which the token expires.
  • scope (list) – List of scopes to request in base oauth flow.
class dropbox.oauth.OAuth2FlowResult(access_token, account_id, user_id, url_state, refresh_token, expires_in, scope)

Bases: dropbox.oauth.OAuth2FlowNoRedirectResult

Authorization information for an OAuth2Flow with redirect.

__init__(access_token, account_id, user_id, url_state, refresh_token, expires_in, scope)

Same as OAuth2FlowNoRedirectResult but with url_state.

Parameters:url_state (str) – The url state that was set by DropboxOAuth2Flow.start().
classmethod from_no_redirect_result(result, url_state)
exception dropbox.oauth.ProviderException

Bases: exceptions.Exception

Dropbox redirected to your redirect URI with some unexpected error identifier and error message.

The recommended action is to log the error, tell the user something went wrong, and let them try again.