Authentication

You'll need to authenticate your requests in order to read or write to any private resources on the Lightfunnels API. In this guide, we'll look at how authentication works. Lightfunnels uses the industry-standard protocol for authorization, OAuth2.

The access token

Think of the access token as a password that lets your app perform actions on an account.

Your app will have a different access token to each account that you want to access. The access token helps identify which account you are trying to access as well as what actions (see scopes) you are allowed to take on the account.

Getting an access token

In order to get the access token for your account, you need to perform the following steps:

1. Send the user to a consent screen to grant permissions to your app
2. Request the access token and save it in order to use it in all your requests

Let's get started

Step 1 - Consent screen

In order to get an access token, you have to ask the user for the permissions that you want to use.

The way you do that is through a consent screen.

To create a consent screen you will need the make a GET request in the following format:

https://app.lightfunnels.com/admin/oauth?client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope={{scopes}}&state={{state}}

• client ID that you will get after creating your app. Example: 9461026524765762404265764243
• A comma separated list of scopes that you want to get the permission for. Example products,orders
• Redirect URI where the user will be redirected after they accept the permissions. Example https://yourapp.com/redirect
• Optional: state parameter that will be returned to you in the redirect URI. Example 123.

Important: The redirect URI must be whitelisted in your app configuration.

Using the example values above, this is what your consent screen URL would look like:

https://app.lightfunnels.com/admin/oauth?client_id=9461026524765762404265764243&redirect_uri=https://yourapp.com/redirect&scope=products,orders&state=123

Step 2 - Getting your access token

Once the user accepts the requested permissions on the consent screen, they will get redirected to the redirect URI that you used in Step 1, with an authorization code variable added in the query string.

Exchange the code by sending a POST request to https://api.lightfunnels.com/api/v3/access_token. The body must be application/x-www-form-urlencoded and contain:

• grant_type: authorization_code
• code: the code you received
• redirect_uri: the same redirect URI you used in Step 1
• client_id and client_secret (or send them as HTTP Basic auth)

const response = await fetch('https://api.lightfunnels.com/api/v3/access_token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: 'the authorization code from the query string',
    redirect_uri: 'https://yourapp.com/redirect',
    client_id: 'client_id',
    client_secret: 'client_secret',
  }),
});

if (!response.ok) {
  throw new Error(`Error: ${response.status} ${await response.text()}`);
}

const { access_token, refresh_token, expires_in } = await response.json();

{
  "access_token": "app_v3_...",
  "token_type": "Bearer",
  "expires_in": 7199,
  "refresh_token": "rt_..."
}

Save both tokens in your database. Use the access_token in the Authorization: Bearer header of your API requests.

Step 3 - Refreshing the access token

Access tokens expire after 2 hours. When one expires (or shortly before), get a new pair with the refresh token:

const response = await fetch('https://api.lightfunnels.com/api/v3/access_token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: 'the saved refresh token',
    client_id: 'client_id',
    client_secret: 'client_secret',
  }),
});

const { access_token, refresh_token } = await response.json();

Every refresh returns a new refresh token and the old one stops working. Always save the new one. Refresh tokens expire after 90 days without use.

Upgrading from the old token endpoint

If your app used one of these endpoints, your saved access tokens keep working. To move an install to v3, exchange its old token once:

const response = await fetch('https://api.lightfunnels.com/api/v3/access_token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
    subject_token: 'the old access token',
    client_id: 'client_id',
    client_secret: 'client_secret',
  }),
});

const { access_token, refresh_token } = await response.json();

The response is the same as Step 2. Each install can be upgraded only once; after that, use the refresh token.

Important notes

• The authorization code expires after 10 minutes and works only once. If you need to test again, go through the consent screen again.
• The client secret is private and should never be shared.
• Keep the access and refresh tokens on your server, never in the browser.