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

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.

consent screen

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

Consent screen parameters

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:

Example consent screen URL

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.

You should pass your client_id and client_secret on authorization header, joined by two points character : (should be on the same order as we said) and base64 encoded, then the resulted value should be joined with Basic . You should pass too the code variable on the body of the request, either using search params as below, or nested on an object and json stringified. Here is an example ts code:

const getOAuthToken = async () => {
  const clientId = 'client_id';
  const clientSecret = 'client_secret';
  const tokenUrl = 'https://api.lightfunnels.com/api/access_token';

  // Encode client credentials in Base64
  const credentials = btoa(`${clientId}:${clientSecret}`);

  try {
    const response = await fetch(tokenUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${credentials}`,
      },
      body: new URLSearchParams({
        'code': 'the authorization code from the query string'
      }).toString()
    });

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

    const data = await response.json();
    console.log('OAuth Token Response:', data);
    return data.access_token;
  } catch (error) {
    console.error('OAuth request failed:', error);
    return null;
  }
};

// Call the function
getOAuthToken().then(token => {
  if (token) {
    console.log('Access Token:', token);
  } else {
    console.log('Failed to retrieve access token.');
  }
});

Response example

{
    "access_token": "YOUR_ACCESS_TOKEN",
}

Important notes

  • While testing, the authorization code will only work once. If you need to test again, you will need to go through the consent screen again.
  • The client secret is private and should never be shared.
  • The access token is permanent and should be saved in your database. You will need it for all your requests.