Lego uses CORS to deny requests from other domains than the once we control. OAuth2 authorization is required if you want to create an app that consumes information from the Lego API.

JSON Web Tokens

To authenticate using JWT, post to /api/token-auth/ with a username and password. This will return a token, which can later be used with the following header: Authorization: JWT <insert token here>.

To refresh a token, post to /api/token-auth/refresh with the token in the body. Both these endpoints can be used with JSON and regular forms.

The webapp uses this authentication flow, third party apps should use OAuth2.


Lego has support for OAuth2 authentication using the authorization-code method. Everyone with a valid user and the right permissions is able to create an OAuth2 application. This works in the same way as Login with GitHub or any other OAuth2 system.

You should never expose the client_secret to the public. Never implement the OAuth2 authorization flow in a browser.

The snippet below can be used together with python-social-auth to authenticate with Lego as the user directory.

We currently have two scopes.

  • user - This scope gives read access access to basic user information: Name, username, profile picture, email and the users memberships. This information can be found in /api/v1/users/oauth2_userdata/

  • all - This scope gives full read & write access to everything. Including password change.

from six.moves.urllib.parse import urljoin

from social_core.backends.oauth import BaseOAuth2

class LegoOAuth2(BaseOAuth2):

    name = 'lego'
    EXTRA_DATA = [
        ('id', 'id'),
        ('expires_in', 'expires_in'),

    def api_url(self):
        api_url = self.setting('API_URL')
        if not api_url:
            raise ValueError('Please set the LEGO_API_URL setting.')
        return api_url

    def get_scope(self):
        return ['user'] # Only use ['all'] when necessary (aka. never)

    def authorization_url(self):
        return urljoin(self.api_url(), '/authorization/oauth2/authorize/')

    def access_token_url(self):
        return urljoin(self.api_url(), '/authorization/oauth2/token/')

    def get_user_details(self, response):
        """Return user details from Lego account"""
        fullname, first_name, last_name = self.get_user_names(
        return {'username': response.get('username'),
                'email': response.get('email') or '',
                'fullname': fullname,
                'first_name': first_name,
                'last_name': last_name}

    def user_data(self, access_token, *args, **kwargs):
        return self._user_data(access_token)

    def _user_data(self, access_token):
        url = urljoin(self.api_url(), 'api/v1/users/me/')
        return self.get_json(url, headers={'AUTHORIZATION': 'Bearer %s' % access_token})