Web 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


Web Application Flow

This is a description of the OAuth 2.0 flow from third-party web sites.

If authorization is being performed inside a mobile app you control with an embedded web view, you can use the simplified clientside-only embedded mobile app flow instead. This removes the need for a one-time token exchange from your server, but is not intended for use in browser-based authorization.

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&redirect_uri=REDIRECT_URI&
response_type=code&scope=PERMISSIONS_LIST&state=CSRF_TOKEN

Request Parameters

Param Required Description
client_id Yes Your API Key.
redirect_uri Yes The URI in your app where users will be sent after authorization. Must match a registered redirect_uri for your app. Must be secured with SSL/TLS and must use ‘https’ URI scheme.
login_hint No User’s email.
first_name No User’s first name.
last_name No User’s last name.
response_type Yes Always code in the web OAuth2 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. Should use urlsafe encoding and should generally not exceed 100 characters.

Example URL

https://sandbox.thelevelup.com/oauth2/authorizations/new?
client_id=23eef8c2895ce66eb4500bb5e324b200f5339e6fe6d8665f6de0205f43f3b563&
redirect_uri=https://example.com/oauth2_redirect_uri&
response_type=code&scope=read_user_basic_info%20read_qr_code&
login_hint=sandboxdevexample@thelevelup.com&state=8675309


2. LevelUp redirects back to your site

If the user accepts your request, LevelUp redirects back to your site with a one-time code and the state you provided in the previous step as URL parameters in the form REDIRECT_URI?code=CODE&state=PASSED_STATE. If the states don’t match, the request has been made by a third party and the process should be aborted.

If there is an error, the user will still be redirected; however instead of a code param there will be an error param stating the error case.

The redirect URI must be HTTPS.

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.

Example Redirect URL

https://example.com/oauth2_redirect_uri?
code=1-f078f7b58014560cd26c6679dfbd04876e35d41bd7b00c7105ac1d3a8f68ba&state=8675309

3. Exchange one-time code for an access token

Using the code passed in from the previous step:

URL

POST https://www.thelevelup.com/oauth2/tokens

POST Parameters

The parameters should be form encoded in the body of the request.

Param Required Description
client_id Yes Your API Key.
client_secret Yes Your client secret.
code Yes Code received in the REDIRECT_URI.
grant_type Yes Always authorization_code.
redirect_uri Yes The redirect_uri you used in the original request.

cURL Example

curl -X POST -H Accept:application/json \
-F client_id=23eef8c2895ce66eb4500bb5e324b200f5339e6fe6d8665f6de0205f43f3b563 \
-F client_secret=4d71e958b9fb6a62af624390c4ef394df15d168ea12b3b12735643ff0694520f \
-F code=1-f078f7b58014560cd26c6679dfbd04876e35d41bd7b00c7105ac1d3a8f68ba \
-F grant_type=authorization_code https://sandbox.thelevelup.com/oauth2/tokens \
-F redirect_uri=https://example.com/oauth2_redirect_uri

Since this request requires the client_secret, it must be made from your server, not directly from consumer devices. The client_secret should never be shipped in apps or exposed to web clients directly. Make sure you also take care that the client_secret is never checked in to any source control (git, mercurial etc).

The one-time code expires after 10 minutes. If you try to exchange the code for a token after the expiration time or more than once, the request will be rejected and any token already granted will be invalidated.

Response

By default, the response will take the following form:

{"access_token":"e72e16c7e42f292…"}

4. 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.