Mobile Authorization Flow

Resources and Guides

Overview

OAuth 2.0 is a protocol that lets external apps securely request authorization to private details in a user’s LevelUp account.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique API Key (Client ID) and Client Secret. The Client Secret should not be shared.

LevelUp’s OAuth flow handles user authorization, and in the in the case a user account does not exist for a given email, provides the means for registering a new user account.

LevelUp’s permissions model enables applications to securely request a rich set of permissions from LevelUp users and merchants. The full list of available permissions can be found on our permissions list page.

Users can manage their connected apps through their Control Panel on the LevelUp website:

LevelUp Manage Connected Apps


Mobile Application Flow

This is a description of the OAuth 2.0 flow within third-party mobile applications.

If authorization is being performed from a web app or is using a system browser that could expose request URLs, you must use the full web authorization flow instead. This requires an additional step after user authorization for a one-time token exchange from your server.

1. Redirect user to request LevelUp access

URL

GET https://www.thelevelup.com/oauth2/authorizations/new

Request URL Format

https://www.thelevelup.com/oauth2/authorizations/new?
client_id=API_KEY&response_type=token&embedded=true&scope=PERMISSIONS_LIST&
login_hint=EMAIL_ADDRESS&state=CSRF_TOKEN

Request Parameters

Param Required Description
client_id Yes Your API Key.
login_hint No User’s email.
first_name No User’s first name.
last_name No User’s last name.
response_type Yes Always token in the embedded mobile flow.
embedded Yes Always true in the embedded mobile flow.
scope Yes Space-separated list of permission names that the access token will have granted to it.
state Yes Unique random token generated to verify using CSRF protection.

Example URL

https://sandbox.thelevelup.com/oauth2/authorizations/new?
client_id=23eef8c2895ce66eb4500bb5e324b200f5339e6fe6d8665f6de0205f43f3b563&
response_type=token&embedded=true&scope=read_user_basic_info%20read_qr_code&
login_hint=sandboxdevexample@thelevelup.com&state=8675309


2. Listen for redirect

If the user accepts your request, LevelUp redirects back to a URL with an access token (user token) and the state you provided in the previous step appended to the URL in the form #access_token=NEW_ACCESS_TOKEN&state=STATE.

Redirect URL Format

Success:

https://www.thelevelup.com/oauth2/authorizations/fake_target#
access_token=NEW_ACCESS_TOKEN&state=STATE

Failure:

https://www.thelevelup.com/oauth2/authorizations/fake_target#
error=SOME_ERROR_CODE&error_description=SOME_DESCRIPTION

Example Redirect URL

https://sandbox.thelevelup.com/oauth2/authorizations/fake_target#
access_token=1285-1595e9be7df87dbf36b80d8b2a80200eea924550017395cc62e0587cef8883&
state=8675309

Your mobile app should use the appropriate mechanism for WebView/UIWebView or your platform’s equivalent to intercept this redirect and parse out the state and access_token from the URL, or the error and error_description in the event of a failure.

If the state doesn’t match the one passed in on your initial request, the request has been made by a third party and the process should be aborted.

Note: In the event that the user’s email is not associated with a LevelUp account, LevelUp will create a user account and ask the user to add a funding source via a web form.

3. Use the access token to access the API

The access token (user token) allows you to make requests to the API on behalf of a user. For details, see the LevelUp API documentation.