The LiveSwitch Contact and Concierge API utilizes a simple REST API to allow you to integrate your application.

Before you get started, there are a couple basic concepts you should understand. Please note that this page uses "callback URL" and "redirect URL" interchangeably - this is the URL, on your site, that you want your user to be directed to post-login.

Basic Concepts

Authentication

LiveSwitch uses OAuth for authentication, and so, in order to authenticate your users to LiveSwitch, you'll need 3 things:

1. A Developer App (which has your client id and secret)
2. A LiveSwitch User Account (which your user will have purchased from LiveSwitch)
3. An Access Token (which this guide will show you how to generate using #1 and #2 above)

Developer Apps

The Developer App contains a name, client id and secret, and callback URL that you can use to create OAuth tokens for your users. The flow is simple:

1. Your user clicks a button in your application to log in to LiveSwitch.
2. You create a login URL using the Developer App information (see below for details) and direct the user there. The URL contains a "client id" (so we know the request is coming from you) and a "callback URL" (so we know where to send them after they have logged in).
3. The user logs in to LiveSwitch. They are presented with the Developer App name when authenticating.
4. We direct the user back to you. You can (optionally, depending on your login method) use the secret to convert an auth token to an access token.

That's it! You can create an application from the Developer Apps page. Feel free to create one for each of "Staging", "Production", or "Development" etc.

This documentation system

This documentation is set up to use your existing LiveSwitch account to automatically create a token that you can use directly from these pages - nice and simple. That makes it extremely easy for you to explore and test the APIs. These tokens should NOT be used in your actual application; you need to use your Developer App for that. To log your users into your app, follow the guide below.

Ready? Let's go!

Creating your first integration

Step 1 : Getting a Developer App

In order to create your application, you first need a Developer App. Go to Developer Apps and click "Add" and fill out the name for your app, and the URL that you will use for the callback after the user logs in. This typically is something like "https://example.com/integrations/liveswitch/callback. This app will be used to determine permissions, add attributes, set up callbacks and login URLs, and so on. Often, developers will create multiple applications, like "Development", "Staging", and "Production".

Note that your users will still log in to their own organizations with their own email and password like normal.

Step 2 : Getting a LiveSwitch User Account

Once you have your Developer App created, you'll need a LiveSwitch User Account to use for making API requests. If you already have a LiveSwitch User Account, you can log in using that user account. If you do not have access to a LiveSwitch User Account, you can contact [email protected] for a free trial.

If you are working on behalf of an organization that does have LiveSwitch access (for example, you are a contractor working for Company ABC which is a customer of LiveSwitch), we would recommend that you request that organization provide you with a LiveSwitch User Account you can use.

Your LiveSwitch User Account can be used to log into this documentation system, so you can easily see if your account will work by logging in .

Step 3 : Creating an Access Token

Once you have a Developer App and a LiveSwitch User Account, you will need to go through an OAuth authorization flow. This will grant your Developer App permission to take actions on behalf of the LiveSwitch User Account.

Depending on which style of application you are building, you can use the Token Exchange or Code Exchange authorization model. The Code Exchange is a little more complex (not much!), but more secure, it also supports background refreshing of your access tokens. It requires a backend, as you will need to use your client secret. The Token Exchange is simpler, and does not require a client secret, but is less secure and will require a full browser redirect to refresh the token.

The goal of either one of these models is to create an access_token which is used in the Authorization header of your HTTP requests like so: Authorization: Bearer abcdefg

Take a look in the API Reference for lots of examples of how to call the API with your newly created token.

Code Exchange: For Server Side Apps

A Code Exchange is done in four steps.

1. Your app creates a login GET-style URL with a series of parameters to tell the auth server some information about your application, and what permissions you are requesting on behalf of the user.
2. The user is redirected to that URL, logs in, and authorizes your application
3. Next, the auth service redirects back to your application, with a query string "code" parameter
4. You use that code to request the access token!

Step 1: Creating the login url

The login URL is: https://supbubble-prod.us.auth0.com/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=openid%20profile%20email%20offline_access%20conversations.write%20contacts.write%20webhooks.write%20me&state=&nonce=&audience=https://public-api.production.liveswitch.com/

The parameters are as follows:

Note that the "redirect_uri" is the URL on your server where the authentication will be directed when the user has logged in successfully. The URL you pass MUST BE WHITELISTED in your list of allowed callback urls as defined in your Developer Apps area. This prevents hijacking of the token by malicious actors.

Step 2: Redirecting and logging in

This one is simple, just redirect the user to the URL you created in step one. The login will be handled for you.

Step 3: Retrieving the "code"

In step 1, you passed in a "callback url". This is the URL the user will land on next. It will have a "code" query parameter passed to it by the auth server. The URL will look like this:

https://my-callback-url.com/path?code=user-code

Step 4: Exchanging the code for an access token

You can convert this parameter into an access token by POSTing it to the token URL:

https://supbubble-prod.us.auth0.com/oauth/token

For details, view the documentation on this API endpoint. You will need to pass grant_type=authorization_code to get the access token.

Refreshing

In addition to the access_token, the response from the code exchange returns a refresh_token; the offline_access scope is required for this capability. This token may be stored and used to retrieve a new access_token in the future by posting it to the refresh endpoint:

https://supbubble-prod.us.auth0.com/oauth/token

For details, view the documentation on this API endpoint. You will need to pass grant_type=refresh_token to get the refresh token.

Token Exchange: For Single Page Apps Without a Backend

A Token Exchange is done in three steps.

1. Your app creates a login GET-style URL with a series of parameters to tell the auth service some information about your application, and what permissions you are requesting on behalf of the user.
2. The user is redirected to that auth service URL, logs in, and authorizes your application.
3. The auth service redirects back to your application, with a hash string "access_token" parameter.

Step 1: Creating the login url

The login URL is: https://supbubble-prod.us.auth0.com/authorize?response_type=token&client_id={client_id}&redirect_uri={redirect_uri}&scope=openid%20profile%20email%20offline_access%20conversations.write%20contacts.write%20webhooks.write%20me&state=&nonce=&audience=https://public-api.production.liveswitch.com/

The parameters are as follows:

Note that the "callbackUrl" is the URL on your server where the authentication will be directed when the user has logged in successfully. The URL you pass MUST BE WHITELISTED in your list of allowed callback URLs as defined in your Developer Apps area. This prevents the hijacking of the token by malicious actors.

Step 2: Redirecting and logging in

This one is simple, just redirect the user to the URL you created in step one. The login will be handled for you.

Step 3: Retrieving the "access_token"

In step 1, you passed in a "callback url". This is the URL the user will land on next. It will have an "access_token" parameter in the hash (#) parameter. The URL looks like this:

https://my-callback-url.com/path#access_token=abcdefg

Now you can use this access token in your code to call the API. Do so with a standard Authorization header with a Bearer token: Authorization: Bearer abcdefg

Take a look at the API Reference for many examples of how to call the API with your newly created token.

Refreshing access tokens

To refresh your access token when using token-based auth, simply direct the user back to the login URL you created in Step 1. As long as their session is still valid, they will be automatically detected as logged in, and return to your callback URL without being prompted to log in again.

💬 We're here to help!

If you run into any problems, please contact [email protected] and we'll get back to you right away.

We're excited you're here! 💙