> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth
As a LoyaltyLion partner, you can authenticate with our API as an OAuth client. Our server implements the [OAuth 2.0 specification](https://tools.ietf.org/html/rfc6749).
OAuth authentication is designed **only** for LoyaltyLion partners building
apps to be used across many stores. If you're building an integration for a
single store, [use an API key](/api-reference/authentication/api-keys).
## Register your OAuth app
Before you can authenticate with OAuth, you'll need to register your app with LoyaltyLion. To register a new OAuth app with LoyaltyLion, please email [partnersupport@loyaltylion.com](mailto:partnersupport@loyaltylion.com) with the following information:
| Required | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Your company/app name |
| `description` | Short description (max 150 characters) of your app |
| `url` | URL to your company/app |
| `image_url` | Copy of your company logo or link to a press pack |
| `install_url` | Your install URL, must be `https` Merchants who initiate installation from their LoyaltyLion account are 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](#initiate-oauth-2-0-approval). |
| `redirect_url` | Your redirect URL, must be `https` We redirect merchants here once they approve access for your app, for example: `https://app.example.com/auth/loyaltylion`. Landing on this page should initiate [token exchange](#acquire-an-access-token) |
Once we've approved your OAuth 2.0 app, 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.
## Perform the OAuth 2.0 flow
### Initiate OAuth 2.0 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 parameters:
| Param | Required | Description |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client_id` | yes | Your client id |
| `scope` | yes | A comma separated list of [resource scopes](#resource-scopes) |
| `redirect_uri` | yes | The return URL, which must match the URL provided to us at registration |
| `state` | no | An encoded string that can be used to lookup and restore the previous state of your app, for example to identify users who are sent back to your app after authorization is complete |
#### Example authorize URL:
```bash theme={null}
# 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 app name,
description and logo and ask them to approve the requested scopes.
### Acquire access token
If the user approves the request, we'll redirect them to your `redirect_uri` including a `code` as query param you can swap for an `access_token`.
For example:
```
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.
```bash theme={null}
# 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:
```json theme={null}
{
"access_token": "e1c752f1b5cd8b743148a586e573b679",
"scope": "read_customers"
}
```
### Use access token
Once you've received the access token, use it to make authenticated API requests allowed by the approved scopes. To do so, pass the access token using the [bearer authentication scheme](https://tools.ietf.org/html/rfc6750).
```bash theme={null}
# 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 can only create webhooks for resources permitted by the token's scope.
| Scope | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `read_customers` | Read-only access to customers, including their points, tiers, rewards and activities. Doesn't include orders. |
| `write_customers` | Read and write access to customers. Can add and remove customer points, change tiers and trigger customer activities. |
| `read_unsubscribes` | Read-only access to the loyalty email unsubscribes list and unsubscribes webhook |
| `write_unsubscribes` | Read and write access to the loyalty email unsubscribes list. Can add emails to the list. |
| `read_orders` | Read-only access to orders. |
| `write_orders` | Read and write access to orders. Can create, update and cancel orders. |
| `write_configuration` | Modify program configuration, such as rules and rewards |
| `read_reviews` | Read-only access to reviews. |
| `write_reviews` | Read and write access to reviews. Can create, update and delete reviews. |