Introduction

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.

Use cases

Decide which authorization flow to choose based on your use case.

Read more about creating LiveChat apps or go straight to Developer Console and start building.

Postman collection

You can find all the requests from the Agent and Customer authorization flows in Postman. Remember to replace sample parameters with your own.

Agent authorization flows

To find details about authorizing calls to the Agent Chat API and the Configuration API, please see Agent Authorization.

Customer authorization flows

To find details about authorizing calls to the Customer Chat API, please see Customer Authorization.

Token limitations

• 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 too_many_redirects error details.

Redirect URI rules

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 (http://, https://) - is required and must match exactly. See examples 10 and 11 in the table below.
• host (google.pl, 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 (/info, /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.

Examples

Errors

All authorization errors redirect to the error page https://accounts.livechat.com/ooops, while authentication errors redirect to the login page https://accounts.livechat.com/.

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). Additional exception_details may be passed with detailed information.

If you're looking for answers, see Authorization FAQ.

Authorization errors

invalid_request

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

unauthorized_client

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

access_denied

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.

unsupported_response_type

The authorization server does not support obtaining a token using this method. Possible reasons:

• response type is not code or token

invalid_scope

The requested scope is invalid, insufficient, unknown or malformed. Possible reasons:

• scope not found
• scope name not found
• an app requires the administrator scopes, but instead, an agent user was logged in

server_error

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.

temporarily_unavailable

The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. Currently not used.

unsupported_grant_type

The authorization grant type is not supported by the authorization server.

• using disabled authorization grant type, for example client credentials grant; read more...

invalid_grant

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

invalid_client

Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). Possible reasons:

• using refresh token with wrong client id

missing_grant

The client is missing granted rights. Possible reasons:

• grants were rejected
• grants were never given
• client changed required grants

Exception details

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

Authentication errors

invalid_request

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.

unauthorized

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 entity_id.

server_error

The server encountered an unexpected condition that prevented it from determining identity.

Not helpful? See server_error in Authorization errors.

access_denied

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.

identity_lost

The identity was removed due logout, password reset, remote logout, etc.

credentials_login_disabled

Identity has disabled credentials login strategy. Identity should be verified with other stategies like Google Oauth or SAML.

Contact us

If you have questions, see Authorization FAQ or contact us at developers@text.com.