Introduction

Chat.io uses OAuth 2.0 protocol for authentication and authorization for all of its services. Before you continue, make sure you understand the following difference:

  • Authentication is making sure that somebody really is who they say they are.
    Example: Checking your passport at the security check is authentication.

  • Authorization is assigning rules about who is allowed to do what.
    Example: Allowing you to take a first class seat is authorization.

Overview

In terms of chat.io 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. There are five authorization flows available for different ways of interacting with chat.io APIs.

Basic use cases

Authorizing API calls

The most popular tool used by developers are Customer API and Agent API. Calling Agent API methods on behalf of chat.io user is as simple as including Authorization: Bearer <access_token> HTTP header in each call. Calling Customer API requires an additional steps to get a different access token. Find out how to acquire the access tokens in the sections below.

Authentication service

You can authenticate users of your app using chat.io authorization flows. You can leverage the existing chat.io user base and distribute apps for the community of chat.io users without the need of building your own authentication service.

Connect with chat.io

Let’s say you have a service which can import chat data from the external sources. You can use a Sign in with chat.io SDK to create something like “Connect with chat.io” button. This way your users can connect their chat.io accounts to your service with just a few clicks.

App authorization flows

All apps integrated with chat.io must be first created in chat.io Developers Console.

Note: If you want to use Customer API you will need an additional authorization flow. Check the Customer Authorization section.

When a user starts using your app, they will see what parts of his account your app will have access to. When they grant the access, your app will receive an access_token that will let you authorize Agent API or Configuration API calls.

There are a few scenarios in which you can acquire an access_token:

Sign in with chat.io

“Sign in with chat.io” button is the easiest way to collect access_token from a chat.io user.

In this scenario, chat.io user enters your website with a “Sign in with chat.io” button installed. After clicking the button, they enter chat.io login and password in a pop-up window and grant access to some parts of their account.

In return, you acquire an access_token which can be used to call Agent API methods.

Read more how to implement this flow in a dedicated “Sign in with chat.io” article.

Public web apps

Coming soon

Public web apps are JavaScript applications that can access any chat.io customer account.

To set up your own public app, you must define the URL of the app and the list of scopes – parts of chat.io account your app will have access to. chat.io customer who enters your app URL is be asked to enter their login and password and grant access for your app.

Then, the user is redirected to your app with access_token included in the URL.

1. Create the app

Go to Developers Console and create a new “chat.io OAuth 2.0 Client” app. Redirect URI is the address of your app that will receive access_token in a URL. Scopes is a list of permissions your app will get.

2. Redirect to chat.io OAuth Server

Example redirection to chat.io OAuth Server:

https://accounts.chat.io/
  ?response_type=token
  &client_id=2261a58dfe1420acc0dc1bd77158f7ac
  &redirect_uri=https%3A%2F%2Fmy-application.com
  &state=i8XNjC4b8KVok4uw5RftR38Wgp2BFwql

When a user runs your app, you should redirect their browser to the following URL:

https://accounts.chat.io/

with the following URL params:

  • response_type=token
  • client_id – you received it when you created the app in Developers Console.
  • redirect_uri – URL of your web application that chat.io OAuth Server will redirect the user back after successful authorization. It must be one of the URLs that you entered when creating the app in the previous step.
  • state – you can provide here any value that might be useful to your application. It is strongly recommended to include an anti-forgery token here mitigate the cross-site request forgery.

3. Acquire the access token

Example redirection back to your app:

https://my-application.com/
  #access_token=1/fFBGRNJru1FQd44AzqT3Zg
  &token_type=Bearer
  &expires_in=1209600
  &state=i8XNjC4b8KVok4uw5RftR38Wgp2BFwql

After successful authorization, the user is redirected back to your app. The URL will include a number of params in the hash section of the URL:

  • access_token – token you can use to call REST API methods on behalf of the user.
  • expires_in – number of seconds the access_token will be valid. When it expires, you will need to repeat the authorization process to get the new access_token.
  • state – value of the state param that you passed in redirection to chat.io OAuth Server.
  • token_type=Bearer

Your application should remember access_token in localStorage or a cookie until it expires. Caching the token prevents you from redirecting the user to chat.io OAuth Server every time he visits your app.

Private web apps

Private web apps are JavaScript applications that are available only to agents from a single chat.io account. If you want to build an internal app for your chat agents only, this is a good way to go.

Private web apps work the very same way like public web apps. Please refer to that documentation to understand how it works.

To start building a private web app, set it up chat.io Developers Console.

Server-side apps

Server-side apps are applications that have access to user’s data for unlimited time. Private and public server-side apps have the same authorization flows. Public server-side apps are not available yet.

When your application wants to acquire the access_token, you must redirect the user to chat.io OAuth Server only once. After successful authorization, the user is redirected back to your app along with a single-use authorization code.

Your application exchanges the authorization code for an access_token and refresh_token. From now now, you can generate new access_tokens indefinitely without any action required from the user.

1. Create the app

Go to Developers Console to create a new server-side app. Redirect URI is the address of your app that will receive authorization code in a URL. Scopes is a list of permissions your app will get.

2. Redirect o chat.io OAuth Server

Example redirection to chat.io OAuth Server:

https://accounts.chat.io/
  ?response_type=code
  &client_id=86pp8cqeg2ac5fimbs8gibluu16ugyvs
  &redirect_uri=https%3A%2F%2Fmy-application.com
  &state=f3NtEuZ5AuxsmnVAzcyLGm17aAaltJTv

Start with redirecting your user to the following address: https://accounts.chat.io/

Required URL parameters:

  • response_type=code
  • client_id – you received it when you created the app in Developers Console.
  • redirect_uri – URL of your web application that chat.io OAuth Server will redirect the user back after successful authorization. It must be one of the URLs that you entered when creating the app in the previous step.

Optional URL parameters:

  • state – provide any state that might be useful to your application. It will be included in the redirection to redirect_uri endpoint.
    It is strongly recommended to include an anti-forgery token in the state to mitigate the cross-site request forgery.

3. Acquire the code

Example redirection back to your app:

https://my-application.com/
  ?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
  &state=f3NtEuZ5AuxsmnVAzcyLGm17aAaltJTv

When the user approves the access request, they are redirected back to your app. The URL will include code param which should be used to acquire access_token and refresh_token.

If the user does not approve the request, chat.io OAuth Server will not redirect the user to your application.

4. Exchange code for access token and refresh token

Example request:

curl "https://accounts.chat.io/token" \
  -X POST \
  -d "grant_type=authorization_code&\
  code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&\
  client_id=86pp8cqeg2ac5fimbs8gibluu16ugyvs&\
  client_secret=nBdMN8d7MEp1YYo3&\
  redirect_uri=https://my-application.com"

To exchange the code for an access_token and refresh_token, you should perform an HTTP POST request to the following URL:

https://accounts.chat.io/token

Required parameters:

  • grant_type=authorization_code
  • code – the authorization code returned from the initial request.
  • client_id – you received it when you created the app in Developers Console.
  • client_secret - you received it when you created the app in Developers Console.
  • redirect_uri – URL of your web application that chat.io OAuth Server will redirect the user back after successful authorization. It must be one of the URLs that you entered when creating the app in the previous step.

Example response:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "refresh_token": "-/khgiugfalskdbcakg2347o8326",
  "expires_in": 3920,
  "token_type": "Bearer"
}


The response will include the following params in JSON format:

  • access_token – token you can use to call REST API methods on behalf of the user.
  • expires_in – number of seconds the access_token will be valid. When it expires, you will need to generate new access_token using refresh_token (read Using the refresh token for more details).
  • refresh_token – token that can be used to generate new access tokens.
  • token_type=Bearer

Using the refresh token

Example request:

curl "https://accounts.chat.io/token" \
  -X POST \
  -d "grant_type=refresh_token&\
  refresh_token=-/khgiugfalskdbcakg2347o8326&\
  client_id=86pp8cqeg2ac5fimbs8gibluu16ugyvs&\
  client_secret=nBdMN8d7MEp1YYo3"

To obtain a new access_token, your application must send an HTTP POST request to the following endpoint:

https://accounts.chat.io/token

Required parameters:

  • grant_type=refresh_token
  • refresh_token – value of refresh token you received in the previous step.
  • client_id – you received it when you created the app in Developers Console.
  • client_secret - you received it when you created the app in Developers Console.

Example response:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "refresh_token": "-/khgiugfalskdbcakg2347o8326",
  "expires_in": 3920,
  "token_type": "Bearer"
}


The response will include the following params in JSON format:

  • access_token – token you can use to call REST API methods on behalf of the user.
  • expires_in – number of seconds the access_token will be valid. When it expires, you will need to generate new access_token using refresh_token (read Using the refresh token for more details).
  • refresh_token – token that can be used to generate new access tokens.
  • token_type=Bearer

Revoking tokens

Revoking a token:

curl "https://accounts.chat.io/token\
  ?token=<access_token|refresh_token>"
  -X DELETE

In some cases a user may wish to revoke access given to an application. The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

Validating the access token

Validating the access_token:

curl "https://accounts.chat.io/info"
  -H "Authorization: Bearer <access_token>"

You can validate an access_token by making an HTTP request to the following endpoint:

https://accounts.chat.io/info

Please note that refresh tokens are not supported for direct validation. If access_token was obtained with with the use of a refresh_token, response will return both tokens.

Example response:

{
  "access_token": "hgDBq88bSw-UHBXnm1Q_Bw",
  "expires_in": 3564,
  "refresh_token": "wB_Q1mnXBHU-wSb88qBDgh", // optional
  "client_id": "14c26ac43f2123dcf8a76ff58b319930",
  "scope": "email,manage_accounts",
  "token_type": "Bearer",
  "entity_id": "name@domain.com",
  "license_id": 1520
}


The response will include the following params in JSON format:

  • access_token – token you can use to call REST API methods on behalf of the user.
  • expires_in – number of seconds the access_token will be valid. When it expires, you will need to generate new access_token using refresh_token (read Using the refresh token for more details).
  • refresh_token – token that can be used to generate new access tokens.
  • client_id – you received it when you created the app in Developers Console.
  • scope – comma-separated list of permissions that access_token has access to.
  • token_type=Bearer
  • entity_id – chat.io’s user login.
  • license_id – chat.io’s user account number.

Notes

Limitations

There is currently a limit of 25 refresh tokens per client per user. When limit is reached, the oldest token is automaticaly revoked (with rabbitmq publishing).

Another limitation is 3 redirects in 30 seconds to chat.io OAuth 2.0 server per client per user. When limit is reached, server redirects to error page with too_many_redirects error detail.

Redirect URI considerations

Client configuration allows adding many redirect URIs. The redirect URIs are separated by comma. Authorization request redirect URI is valid when matches one of the client’s configuration URIs.

URI is composed of several parts:

  • scheme (http://, https://) - is required and must match exactly,
  • host (google.pl, localhost:3000, …) - hostname or ip and optional port, is required and must match exactly,
  • path (/info, /test, …) - is optional, client redirect URI path must be a substring of authorization request redirect path, path traversals are forbidden,
  • query (?size=20, …) - is forbidden,
  • fragment (#paragraph) - is forbidden.

Customer authorization flow

To authorize Customer API you will need different access token than for the Agent API or Configuration API.

Creating new customer along with customer access token

You can create a new customer on licence or use an existing identity. The <ACCESS_TOKEN> mentioned below is the one that you get from the app authorization flow. Required scope: customers.identity--manage.

POST https://accounts.chat.io/customer/ -H "Authorization: Bearer <ACCESS_TOKEN>"

Required parameters

  • client_id - identifies the client application that is making the request
  • response_type - oauth2 standard, should use token
  • redirect_uri - the value of this parameter must exactly match one of the values listed in application

Optional partametres

  • customer_id - ID of existing customer, if empty new customer_id is created
  • valid_for - Optional for overriding default token expiration time

Example response

{
    "access_token": "dev-J7ssSZhSSbShcZxrv580FA",
    "client_id": "238ac4c3c3628880aca289c6d700d2c5",
    "entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
    "expires_id": 3600
}

Customer chat url

It’s possible to create customer direct chat url using license_id and access_token.

Example URL

https://accounts.chat.io/customer?
  access_token=ae19bb31-803a-46f3-53ac-3b7d2564fe7e&
  redirect_uri=https://chat.io/direct/1234"

Scopes list

Chats scopes

Scope permission Description
chats--all:read normal Read access for all license chats
chats--my:read normal Read access for the chats I belong to
chats.conversation--all:write normal Write access for conversation data of all license chats
chats.conversation--my:write normal Write access for conversation data of chats I belong to
chats.meta--all:write administrator Write access for meta data of all license chats
chats.meta--my:write normal Write access for meta data of chats I belong to
  • chats.conversation applies to:
    • chat events
    • chat properties
    • thread properties
  • chats.meta applies to:
    • chat users

NOTICE: currently chats.conversation--all:write allows joining chats too because you have to join the chat to be able to write to it

Multicast scopes

Scope permission Description
multicast:write normal Access for multicast data to agents or customers

Customers scopes

Scope permission Description
customers.ban:write normal Access for banning customers
customers.identity--manage administrator Access for managing customers identities
customers:read normal Read access for customers
customers:write normal Write access for customers

Agents scopes

Scope permission Description
agents--my:write normal Write access for my profile configuration
agents--all:write administrator Write access for all agents profiles configuration

Agents scopes

Scope permission Description
auto_chat_scopes:read administrator Read access for auto chat scopes configuration
auto_chat_scopes:write administrator Write access for auto chat scopes configuration

Properties scopes

Scope permission Description
properties--my:read administrator Read access for chat/thread/events properties configuration (only in my namespace)
properties--my:write administrator Write access for chat/thread/events properties configuration (only in my namespace)
properties--all:read administrator Read access for chat/thread/events properties configuration (all in license)

Webhooks scopes

Scope permission Description
webhooks--my:read administrator Read access for webhooks configuration (only my webhooks)
webhooks--my:write administrator Write access for webhooks configuration (only my webhooks)
webhooks--all:read administrator Read access for webhooks configuration (all in license)
webhooks--all:write administrator Write access for webhooks configuration (all in license, delete only)

Bot agents scopes

Scope permission Description
agents-bot--my:read administrator Read access for bot agents configuration (only my bot agents)
agents-bot--my:write administrator Write access for bot agents configuration (only my bot agents)
agents-bot--all:read administrator Read access for bot agents configuration (all in license)
agents-bot--all:write administrator Write access for bot agents configuration (all in license, delete only)