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 needs a Bearer access token in the Authorization header — this page walks through getting one.
Using these docsThis documentation site automatically creates a token from your logged-in LiveSwitch account, so you can try API calls directly from these pages. That token is for exploring the docs only — never use it in your own application. Follow the steps below to authenticate real users of your app.
What you'll need
| A Developer App | Contains your client_id, client_secret, and whitelisted callback URL(s). Email [email protected] with subject "Create a developer app" and include your callback URL(s), app name/purpose, and primary developer contact. Mention if you need separate Staging and Production apps. |
| A LiveSwitch User Account | The account your app authenticates as. If you don't have one, contact [email protected] or start a free trial. Working on behalf of an existing customer? Ask them to provide you with an account. |
| An access token | What you get at the end of the flow below — put it in Authorization: Bearer {access_token} on every request. |
How the login flow works
- Your app sends the user to a LiveSwitch login URL, built from your
client_idand callback URL. - The user logs in — seeing your Developer App's name — and authorizes your app.
- LiveSwitch redirects back to your callback URL with either a
code(Code Exchange) or anaccess_token(Token Exchange), depending on which flow you use.
Two flows are available:
| Code Exchange | Token Exchange | |
|---|---|---|
| Best for | Apps with a backend | Browser-only apps (SPAs) with no backend |
Needs client_secret | Yes | No |
| Refresh without re-login | Yes, via refresh_token | No — re-redirect through login |
| Security | More secure | Less 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=contacts contacts.write conversations conversations.write documents email me offline_access openid organizations profile projects projects.write recordings tags tags.write webhooks webhooks.write
&audience=https://public-api.production.liveswitch.com/2. Exchange the returned code for tokens
code for tokensPOST 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"
}access_token goes in the Authorization: Bearer header on every API call. Save the refresh_token somewhere durable — you'll need it in the next step, and you won't get a new one until you use it.
3. Refresh when the access token expires
Don't wait for a request to fail with 401 — track expires_in and refresh a bit before it lapses (or refresh reactively on a 401, 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 is the same shape — a fresh access_token and a fresh refresh_token. Overwrite your saved refresh_token with the new one every time — the previous one is invalidated as soon as you use it.
1. Send the user to the login URL
GET https://id.liveswitch.com/authorize
?response_type=token
&client_id={your_client_id}
&redirect_uri={your_whitelisted_callback}
&scope=contacts contacts.write conversations conversations.write documents email me offline_access openid organizations profile projects projects.write recordings tags tags.write webhooks webhooks.write
&audience=https://public-api.production.liveswitch.com/2. Read the access token from the redirect
LiveSwitch redirects back with the token in the URL hash, not a query param:
https://your-callback-url.com/path#access_token=abcdefgUse it directly: Authorization: Bearer abcdefg
3. "Refresh" by logging in again
There's no refresh token in this flow. To get a new access token, redirect the user back through the login URL from step 1 — if their LiveSwitch session is still active, they'll be sent straight back to your callback without being prompted to log in again.
Callback URLs must be whitelistedThe
redirect_uriyou pass must exactly match a callback URL registered on your Developer App, or the login will fail. This prevents malicious actors from hijacking tokens. Email [email protected] with your Client ID and the callback URL if you need to add or change one.
Scopes
Request only the scopes your app needs.
| Scope | Grants |
|---|---|
openid, profile, email | Basic identity info about the logged-in user |
offline_access | Issues a refresh_token (Code Exchange only) |
organizations | Read the user's organization info |
conversations / conversations.write | Read / create & update Conversations (sessions) |
projects / projects.write | Read / create & update Projects |
contacts / contacts.write | Read / create & update Contacts |
recordings, documents | Read recordings, photos, and documents |
tags / tags.write | Read / manage tags |
webhooks / webhooks.write | Read / manage webhook subscriptions — requires org admin rights |
sparks / sparks.write, spark-templates | Read / run Sparky AI reports — see the Sparky AI Reports guide |
Where to go next
Questions? Email [email protected] and we'll get back to you right away.
Updated about 2 hours ago