The Lumo API uses OAuth2 for authentication. To get started:

  1. Obtain an OAuth client ID and secret by creating an app at
  2. Using your client ID, obtain an authorization code by visiting the URL below with your client ID and redirect URL substituted in. (Note that your redirect URL must be URL encoded) this link is used in your app wherever you wish to allow your users to “connect with Lumo” .
  3. Visiting the link above will cause the user’s browser to be redirected to the redirect URL you specified with a query parameter containing the authorization code. The name of this parameter is simply code. In other words, if your redirect URL was http://localhost:8000/authorized/ the browser will be sent to something like http://localhost:8000/authorized/?code=1628975687
  4. Exchange the authorization code together with your client ID and secret for an access token and refresh token by posting the authorization code to the following URL:
curl -X POST -d "code=1628975687&client_id=miW7Nzpn&client_secret=9682978562&grant_type='authorization_code'&redirect_uri=http://localhost:8000/authorized/"


The redirect_uri parameter must match EXACTLY what you specified when creating the app, including the presence or absence of a trailing slash or you will receive an access denied error.

The response to your POST request will look something like:

  "access_token" : "a751p9ipse",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "97851651652871"
  1. Use the access token you have obtained to access a protected resource
curl --header "Authorization: Bearer a751p9ipse"

Access tokens become invalid under the following circumstances:

  • After 30 days have passed (this is the current lifetime of access tokens)
  • The end user revokes their permissions for your app
  • You change the requested scopes for your app. When you do this, all your outstanding tokens which had a different set of scopes become invalid.

To refresh an expired access token, you can post to our token endpoint while specifying ‘refresh_token’ as the grant_type parameter:

curl -X POST -d "client_id=miW7Nzpn&client_secret=9682978562&refresh_token=51971719751&grant_type='refresh_token'&redirect_uri=http://localhost:8000/authorized/"


The response to this request will include both a new access token and a new refresh token- so you should make sure to store this new refresh token.

Code examples

The python code below will create a functioning callback URI that you can use to exchange an authorization code for an access token. To make use of this code sample you will need to create a Lumo app in order to obtain your CLIENT_ID and CLIENT_SECRET. Once you have those, paste them in the indicated variable definitions below. Make sure when creating your app that you specify the REDIRECT_URI value shown in the code below. (Once you are done testing, set the REDIRECT_URI to whatever you are actually using in your app).

Save the code below to a file called, then run:


This will start a server listening on your local callback URI. Now in a browser window, paste the following URL into your address bar and modify the client_id parameter so it matches your actual client_id. When you open the resulting URL you will presented with the Lumo authorization dialog which will prompt you to login (if you have not yet) and then request that you grant your app permissions. If you do grant permissions, the Lumo server will send an authorization code to your local callback and the python code below will exchange the authorization code for an access and refresh token.

import os
import requests
from flask import Flask,request,g

app = Flask(__name__)
app.config['DEBUG'] = True
REDIRECT_URI = 'http://localhost:8000/authorized/'

def exchange_code_for_access_token():
    print request.args.get('code')
    print request.json

    authorization_code = request.args.get('code')
    data={'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI}

    token_url = '%s/oauth2/token/' % SERVER_URL
    print "fetching token from ",token_url
    result =,data=data)
    print result.content
    print result.reason
    print result.status_code
    g.refresh_token = result.json()['refresh_token']
    return "OK"

def use_refresh_token():
    data={'client_id': CLIENT_ID,
            'client_secret' : CLIENT_SECRET,
            'refresh_token' : g.refresh_token,
    token_url = '%s/oauth2/token/' % SERVER_URL
    print "refreshing token from ",token_url
    result =,data=data)
    print result.content
    print result.reason
    print result.status_code
    return result.content

if __name__ == '__main__':
    port = int(os.environ.get('PORT',8000))'',port=port,debug=True)