API — Flask Dance 0.4.2 documentation

### Navigation

- index
- modules |
- previous |
- Flask Dance 0.4.2 documentation »

# API

## Consumers

An OAuth consumer is a website that allows users to log in with other websites (known as OAuth providers). Once a user has gone through the OAuth dance, the consumer website is allowed to interact with the provider website on behalf of the user.

class `flask_dance.consumer.` `OAuth1ConsumerBlueprint`(...)

  A subclass of `flask.Blueprint` that sets up OAuth 1 authentication.

  `__init__`(name, import_name, client_key=None, client_secret=None, signature_method=u'HMAC-SHA1', signature_type=u'AUTH_HEADER', rsa_key=None, client_class=None, force_include_body=False, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, request_token_url=None, authorization_url=None, access_token_url=None, redirect_url=None, redirect_to=None, session_class=None, **kwargs)

    Most of the constructor arguments are forwarded either to the `flask.Blueprint` constructor or the `requests_oauthlib.OAuth1Session` construtor, including `**kwargs` (which is forwarded to `OAuth1Session`). The only arguments that are specific to this class are `base_url`, `request_token_url`, `authorization_url`, `access_token_url`, `login_url`, `authorized_url`, `redirect_url`, `redirect_to`, and `session_class`.

    Parameters: | base_url (str, optional) – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL. request_token_url (str) – The URL specified by the OAuth provider for obtaining a request token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. authorization_url (str) – The URL specified by the OAuth provider for the user to grant token authorization. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. access_token_url (str) – The URL specified by the OAuth provider for obtaining an access token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. login_url (str, optional) – The URL route for the `login` view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}`, so that the URL is based on the name of the blueprint. authorized_url (str, optional) – The URL route for the `authorized` view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}/authorized`, so that the URL is based on the name of the blueprint. redirect_url (str, optional) – When the OAuth dance is complete, redirect the user to this URL. redirect_to (str, optional) – When the OAuth dance is complete, redirect the user to the URL obtained by calling `url_for()` with this argument. If you do not specify either `redirect_url` or `redirect_to`, the user will be redirected to the root path (`/`). session_class (class, optional) – The class to use for creating a Requests session. Defaults to `OAuth1Session`.

  `session`

    An `OAuth1Session` instance that automatically loads credentials for the OAuth provider (if the user has already gone through the OAuth dance).

  `token_getter`(func)

    A decorator used to indicate the function used to retrieve a stored token from a completed OAuth dance.

  `token_setter`(func)

    A decorator used to indicate the function used to store a token from a completed OAuth dance, so that it can be retrieved later.

  `token_deleter`(func)

    A decorator used to indicate the function used to delete a previously-stored OAuth token.

  `token`

    A proxy property for getting, setting, and deleting the stored OAuth token.

  `set_token_storage_session`()

    A helper method to set up the blueprint to store and retrieve OAuth tokens using the Flask session. This will overwrite any custom token accessors you’ve set up. This method is called by the constructor as a default – in general, you shouldn’t call this method yourself.

  `set_token_storage_sqlalchemy`(model, session, user=None, user_id=None, anon_user=None, cache=None)

    A helper method to set up the blueprint to store and retrieve OAuth tokens using SQLAlchemy. This will overwrite any custom token accessors you’ve set up.

    Parameters: | model – A class that represents a database table. At a minimum, it must have a `token` column and a `provider` column. If you’re using a User class, this model must also declare a `user` relation to that class. It is recommended, but not required, that your model inherit from `flask_dance.models.OAuthConsumerMixin`. session – A `sqlalchemy.orm.session.Session` object. If you’re using Flask-SQLAlchemy, this is `db.session`. user – The current logged in user, if any. This can also be a function that returns the current logged in user. This argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application. If you’re using Flask-Login, this is `current_user`. user_id – The ID of the current logged in user, if any. This argument is optional, and is used in the same way as the `user` argument. You do not need to specify both. anon_user – A class that specifies an anonymous user, as opposed to an actual logged-in user. This defaults to `flask_login.AnonymousUserMixin` if Flask-Login is installed. cache – An instance of Flask-Cache. This is optional, but highly recommended for performance reasons.

class `flask_dance.consumer.` `OAuth2ConsumerBlueprint`(...)

  A subclass of `flask.Blueprint` that sets up OAuth 2 authentication.

  `__init__`(name, import_name, client_id=None, client_secret=None, client=None, auto_refresh_url=None, auto_refresh_kwargs=None, scope=None, state=None, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, authorization_url=None, authorization_url_params=None, token_url=None, token_url_params=None, redirect_url=None, redirect_to=None, session_class=None, **kwargs)

    Most of the constructor arguments are forwarded either to the `flask.Blueprint` constructor or the `requests_oauthlib.OAuth2Session` construtor, including `**kwargs` (which is forwarded to `OAuth2Session`). The only arguments that are specific to this class are `base_url`, `authorization_url`, `token_url`, `login_url`, `authorized_url`, `redirect_url`, `redirect_to`, and `session_class`.

    Parameters: | base_url (str, optional) – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL. authorization_url (str) – The URL specified by the OAuth provider for obtaining an authorization grant. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. authorization_url_params (dict, optional) – A dict of extra key-value pairs to include in the query string of the `authorization_url`, beyond those necessary for a standard OAuth 2 authorization grant request. token_url (str) – The URL specified by the OAuth provider for obtaining an access token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. token_url_params (dict, optional) – A dict of extra key-value pairs to include in the query string of the `token_url`, beyond those necessary for a standard OAuth 2 access token request. login_url (str, optional) – The URL route for the `login` view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}`, so that the URL is based on the name of the blueprint. authorized_url (str, optional) – The URL route for the `authorized` view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}/authorized`, so that the URL is based on the name of the blueprint. redirect_url (str, optional) – When the OAuth dance is complete, redirect the user to this URL. redirect_to (str, optional) – When the OAuth dance is complete, redirect the user to the URL obtained by calling `url_for()` with this argument. If you do not specify either `redirect_url` or `redirect_to`, the user will be redirected to the root path (`/`). session_class (class, optional) – The class to use for creating a Requests session. Defaults to `OAuth2Session`.

  `session`

    An `OAuth2Session` instance that automatically loads credentials for the OAuth provider (if the user has already gone through the OAuth dance).

  `token_getter`(func)

    A decorator used to indicate the function used to retrieve a stored token from a completed OAuth dance.

  `token_setter`(func)

    A decorator used to indicate the function used to store a token from a completed OAuth dance, so that it can be retrieved later. This function will also be called when the token is refreshed.

  `token_deleter`(func)

    A decorator used to indicate the function used to delete a previously-stored OAuth token.

  `token`

    A proxy property for getting, setting, and deleting the stored OAuth token.

  `set_token_storage_session`()

    A helper method to set up the blueprint to store and retrieve OAuth tokens using the Flask session. This will overwrite any custom token accessors you’ve set up. This method is called by the constructor as a default – in general, you shouldn’t call this method yourself.

  `set_token_storage_sqlalchemy`(model, session, user=None, user_id=None, anon_user=None, cache=None)

    A helper method to set up the blueprint to store and retrieve OAuth tokens using SQLAlchemy. This will overwrite any custom token accessors you’ve set up.

    Parameters: | model – A class that represents a database table. At a minimum, it must have a `token` column and a `provider` column. If you’re using a User class, this model must also declare a `user` relation to that class. It is recommended, but not required, that your model inherit from `flask_dance.models.OAuthConsumerMixin`. session – A `sqlalchemy.orm.session.Session` object. If you’re using Flask-SQLAlchemy, this is `db.session`. user – The current logged in user, if any. This can also be a function that returns the current logged in user. This argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application. If you’re using Flask-Login, this is `current_user`. user_id – The ID of the current logged in user, if any. This argument is optional, and is used in the same way as the `user` argument. You do not need to specify both. anon_user – A class that specifies an anonymous user, as opposed to an actual logged-in user. This defaults to `flask_login.AnonymousUserMixin` if Flask-Login is installed. cache – An instance of Flask-Cache. This is optional, but highly recommended for performance reasons.

## Models

class `flask_dance.models.` `OAuthConsumerMixin`

  A SQLAlchemy declarative mixin with some suggested columns for a model to store OAuth tokens:

  `id`
    an integer primary key
  `provider`
    a short name to indicate which OAuth provider issued this token
  `created_at`
    an automatically generated datetime that indicates when the OAuth provider issued this token
  `token`
    a `JSON` field to store the actual token received from the OAuth provider