Guides
LiveSwitch Exchange
  1. Getting Started

Authentication

How to authenticate your users and call the LiveSwitch API from your own application.

LiveSwitch uses OAuth 2.0 for authentication. Every API request requires an access token with the Bearer scheme in the Authorization header. This page explains how to get an access token.

📘

Using these docs

This documentation site automatically creates an access token from your LiveSwitch account after you log in. You can use this access token to try API calls directly from these pages. This access token is only for tests in the documentation. It is not for use in your application. The steps below explain authentication for users of your application.

Base URL

Send all API requests to this URL. Each endpoint path starts with /v1.

https://public-api.production.liveswitch.com

The login and token endpoints use a different host, https://id.liveswitch.com.

What you need

A Developer AppContains your client_id, client_secret, and registered callback URLs. To request a Developer App, email [email protected] with the subject "Create a developer app". Include your callback URLs, application name and purpose, and primary developer contact.
A LiveSwitch User AccountYour application authenticates as this account. If you need an account, contact [email protected] or start a free trial. If you work for an existing customer, ask that customer to provide an account.
An access tokenYou receive this at the end of the flow below. Include it in Authorization: Bearer {access_token} on every request.

How the login flow works

The login flow has these steps:

  1. Your application sends the user to a LiveSwitch login URL that uses your client_id and callback URL.
  2. The user sees your Developer App's name at login. The user logs in. The user authorizes your application.
  3. For Code Exchange, LiveSwitch redirects to your callback URL with a code. For Token Exchange, it returns an access_token.

Two flows are available:

Code ExchangeToken Exchange
Best forApps with a backendBrowser-only apps (SPAs) with no backend
Needs client_secretYesNo
Refresh without re-loginYes, via refresh_tokenNo. Requires another redirect through login
SecurityMore secureLess secure

1. Send the user to the login URL

GET https://id.liveswitch.com/authorize
  ?response_type=code
  &client_id={your_client_id}
  &redirect_uri={your_whitelisted_callback}
  &scope=accounts applications applications.write attributes attributes.write contacts contacts.write conversations conversations.write documents email forms guided-instructions me offline_access openid organizations organizations.write profile projects projects.write recordings spark-templates sparks sparks.write tags tags.write webhooks webhooks.write
  &audience=https://public-api.production.liveswitch.com/

2. Exchange the returned code for tokens

POST https://id.liveswitch.com/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "...",
  "client_id": "...",
  "client_secret": "...",
  "redirect_uri": "..."
}

Response:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "v1.MjM0NTY3...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Include access_token in the Authorization: Bearer header on every API call. Save the refresh_token in persistent storage. You need it in the next step. You will receive a new refresh token only after you use the current one.

3. Refresh when the access token expires

Do not wait for a request to fail with 401. Track expires_in. Refresh the access token shortly before it expires. Alternatively, if a request fails with 401, refresh the access token. Then retry the original request once.

Call the same token endpoint with a different grant type:

POST https://id.liveswitch.com/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "v1.MjM0NTY3...",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}"
}

The response uses the same structure. It contains a new access_token and a new refresh_token. Each time, replace your saved refresh_token with the new one. The previous refresh token becomes invalid as soon as you use it.

🚧

Callback URLs must be registered

The redirect_uri must exactly match a callback URL registered on your Developer App. Otherwise, login fails. This prevents token theft by malicious actors. Requests for callback URL additions or changes go to [email protected]. These requests require your Client ID and the callback URL.

Log out

  1. Delete the access token and the refresh token that your application saved.
  2. Send the user to the LiveSwitch logout URL:
GET https://id.liveswitch.com/v2/logout?client_id={your_client_id}

LiveSwitch ends the user's login session.

Scopes

The example login URLs request every scope. In your application, request only the scopes that it needs.

ScopeGrants
openid, profile, emailBasic identity information about the user who logs in. Every integration requires these scopes, regardless of its endpoints.
offline_accessIssues a refresh_token (Code Exchange only)
organizationsRead the user's organization information
conversations / conversations.writeRead, create, and update Conversations. The LiveSwitch UI calls Conversations "Sessions".
projects / projects.writeRead, create, and update Projects
contacts / contacts.writeRead, create, and update Contacts
recordings, documentsRead recordings, photos, and documents
tags / tags.writeRead and manage tags
webhooks / webhooks.writeRead and manage webhook subscriptions. Only administrators can use these endpoints. Regular users receive 403 on all webhook endpoints, also for read requests.
sparks / sparks.write, spark-templatesRead and run Sparky AI reports. See the Sparky AI Reports guide
accounts, applications / applications.write, attributes / attributes.write, forms, guided-instructions, organizations.writeRead or write these resources. Most integrations do not need them.

Where to go next

These pages provide more information:

For questions, email [email protected]. We will reply promptly.

Updated 6 days ago

Did this page help you?