OAuth

If you’re a LoyaltyLion partner, you can authenticate with our API as an OAuth client. Our server implements the OAuth 2.0 specification.

Registering your OAuth application

Before you can authenticate with OAuth, you’ll need to register your application with LoyaltyLion. To register a new OAuth application with LoyaltyLion, please email partnerships@loyaltylion.com with the following information:

  • Your company/app name
  • URL to your company/app
  • Short description (max 150 characters) of your app
  • Copy of your company logo or link to a press pack
  • Your install URL, which must be https

    • Merchants who initiate installation from their LoyaltyLion account will be sent here
    • It should require login / signup to your app
    • Once the merchant is authenticated with your app, it should redirect into the LoyaltyLion OAuth approval flow
  • Your redirect URL, which must be https

    • We’ll redirect merchants here once they approve access for your app, e.g. https://app.example.com/auth/loyaltylion
    • Landing on this page should initiate token exchange

Once we’ve approved your OAuth2 application, we’ll provide you with a client id and secret. Your client secret must be kept private. If you believe it has been compromised, please contact us immediately.

Performing the OAuth2 flow

Initiating OAuth2 approval

To kick off the OAuth flow, start by sending the user to our authorize URL, https://app.loyaltylion.com/oauth/authorize, with the following required parameters:

  • client_id - your client id
  • scope - a comma separated list of resource scopes
  • redirect_uri - the return URL, which must match the URL provided to us at registration

Example authorize URL:

# client_id: 317979793529
# scope: read_customers
# redirect_uri: https://api.example.com/auth/loyaltylion

https://app.loyaltylion.com/oauth/authorize?client_id=317979793529&scope=read_customers&redirect_uri=https%3A%2F%2Fapi.example.com%2Fauth%2Floyaltylion

When a user is redirected to the authorize URL, we’ll show them your application name, description and logo and ask them to approve the requested scopes.

Acquiring an access token

If they approve the request, we’ll redirect them to your redirect_uri including a code as query param you can swap for an access_token.

e.g. https://app.example.com/auth/loyaltylion?code=fe53739dab6d76cc

To exchange the code for a permanent access token, your server should make a POST request with the code, your client id and your client secret.

# client_id: 317979793529
# client_secret: 97b0dc6dde30f189
# code: fe53739dab6d76cc

curl --request POST \
  --url 'https://app.loyaltylion.com/oauth/access-token' \
  --data 'client_id=317979793529&client_secret=97b0dc6dde30f189&code=fe53739dab6d76cc' \
  --include

If the exchange is successful, we’ll return a JSON response containing your permanent access token and a comma separated list of the approved scopes:

{
  "access_token": "e1c752f1b5cd8b743148a586e573b679",
  "scope": "read_customers"
}

Using the access token

Once you’ve received the access token, you can use it to make authenticated API requests allowed by the approved scopes. To do so, pass the access token using the bearer authentication scheme.

# access_token: e1c752f1b5cd8b743148a586e573b679

curl \
  --header 'Authorization: Bearer e1c752f1b5cd8b743148a586e573b679' \
  --header 'Content-Type: application/json' \
  --url 'https://api.loyaltylion.com/v2/customers'

Resource scopes

Scopes let you specify the type of access your app needs, and limit the capability of the associated access tokens. When making your initial request to our authorize URL, you should pass through the scopes needed by your app as a comma separated list.

Our webhooks API is available to all access tokens, but you will only be able to create webhooks for resources permitted by the token’s scope.

ScopeDescription
read_customersRead-only access to customers, including their points, tiers, rewards and activities. Does not include orders.
write_customersRead and write access to customers. Can add and remove customer points, change tiers and trigger customer activities.
read_unsubscribesRead-only access to the loyalty email unsubscribes list and unsubscribes webhook
write_unsubscribesRead and write access to the loyalty email unsubscribes list. Can add emails to the list.
read_ordersRead-only access to orders.
write_ordersRead and write access to orders. Can create, update and cancel orders.