Authorizing API calls
LiveChat uses OAuth 2.1 protocol for authentication and authorization for all of its services. Before you continue, make sure you understand the difference between them.
- Authentication is making sure that somebody really is who they say they are.
E.g.: Checking your passport at the security check is authentication.
- Authorization is assigning rules about who is allowed to do what.
E.g.: Allowing you to take first class seat is authorization.
In terms of LiveChat apps, authentication is when you check the user credentials to see if they are signed in. Authorization is when you look up whether you allow them to do something.
Throughout the document, we'll also use the terms public and private apps:
- public apps are available to all LiveChat customers, who can install it from the LiveChat Marketplace or HelpDesk Marketplace.
- private apps are only available within a LiveChat license that created the app. They're a way to go if you want to build an internal app for your chat Agents only. Unlike public apps, private apps don't ask users for an access grant.
Decide which authorization flow to choose based on your use case.
|Use case||Recommended flow|
|Sending requests to LiveChat API||Personal Access Tokens is the fastest way, but all other flows are also possible.|
|Testing an app during development||Sign in with LiveChat is the fastest, but all other flows are also possible.|
|Building public web apps||Sign in with LiveChat, Implicit grant|
|Building private web apps||Sign in with LiveChat, Implicit grant|
|Building public server-side apps||Sign in with LiveChat, Authorization code grant|
|Building private server-side apps||Personal Access Tokens for the personal use of the app, Sign in with LiveChat or Authorization code grant for all agents within a license|
You can find all the requests from the Agent and Customer authorization flows in Postman. Remember to replace sample parameters with your own.
There's a limit of 25 access tokens per client per user account. When the limit is reached, the oldest token is automatically revoked.
There's a limit of 25 refresh tokens per client per user account. When the limit is reached, the oldest token is automaticaly revoked.
There's a limit of 3 redirects in 30 seconds to the Livechat OAuth 2.1 server per client per user account. When the limit is reached, the server redirects to the error page with the
You can configure many comma-separated redirect URIs for your application. The redirect URI in the Authorization request is valid when it matches one of the URIs configured for your app (client) in Developer Console.
URIs are composed of several parts:
- scheme (
https://) - is required and must match exactly. See examples 10 and 11 in the table below.
- host (
localhost:3000, ...) - a hostname or IP and an optional port; is required and must match exactly. See examples 7, 8, and 9 in the table below.
- path (
/test, ...) - the client redirect URI path must be a substring of the authorization request redirect path; path traversals are forbidden. Optional. See examples 2, 3, 4, 5, and 6 in the table below.
- query (
?size=20, ...) - is forbidden.
- fragment (
#paragraph) - is forbidden.
All authorization errors redirect to the error page
https://accounts.livechat.com/ooops, while authentication errors redirect to the login page
Errors codes are returned in the query strings, in form of the
oauth_exception parameter (for authorization errors) or
identity_exception param (for authentication errors).
exception_details may be passed with detailed information.
If you're looking for answers, see Authorization FAQ.
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Possible reasons:
- wrong HTTP method
- invalid HTTP body encoding
The client is not authorized to request a token using this method. Possible reasons:
- missing client ID
- client ID not found
- refresh token not found
- invalid client secret
- invalid redirect URI
The resource owner or authorization server denied the request. Possible reasons:
- the requested scopes include a scope that wasn't originally granted by the resource owner
Not helpful? See
access_denied in Authentication errors.
The authorization server does not support obtaining a token using this method. Possible reasons:
- response type is not
The requested scope is invalid, insufficient, unknown or malformed. Possible reasons:
- scope not found
- scope name not found
- an app requires the
administratorscopes, but instead, an
agentuser was logged in
The authorization server encountered an unexpected condition that prevented it from fulfilling the request. Possible reasons:
- server down
- server storage down
Not helpful? See
server_error in Authentication errors.
The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. Currently not used.
The authorization grant type is not supported by the authorization server.
- using disabled authorization grant type, for example client credentials grant; read more...
The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. Possible reasons:
- refresh token expired
- access token expired
Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). Possible reasons:
- using refresh token with wrong client id
The client is missing granted rights. Possible reasons:
- grants were rejected
- grants were never given
- client changed required grants
client_id_not_found - wrong client ID, client id does not exists
redirect_uri_not_set - client misconfiguration, the client has not set a redirect URI
invalid_redirect_uri - redirect URI is not one of the client's allowed redirects
too_many_redirects - the server has detected a redirect loop; the client shouldn't redirect too many times
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
Not helpful? See
invalid_request in Authorization errors.
The request is valid, but identity data is wrong or identity does not exists. If identity id is known, it's added to querystring as
The server encountered an unexpected condition that prevented it from determining identity.
Not helpful? See
server_error in Authorization errors.
The identity is known, but access is denied because of business reasons. For example, identity can be banned or have the wrong account version, etc.
Not helpful? See
access_denied in Authorization errors.
The identity was removed due logout, password reset, remote logout, etc.
Identity has disabled credentials login strategy. Identity should be verified with other stategies like Google Oauth or SAML.