- Platform Overview
-
Resources and Guides
-
Getting Started
-
-
-
- Web Authorization Flow
-
-
-
-
-
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
- Order Ahead
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
- Orders
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
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 app 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:
Web Application Flow
This is a description of the OAuth 2.0 flow from third-party web sites.
1. Redirect user to request LevelUp access
URL
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 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.