Third-Party App Authentication

This document provides guidance for third-party applications intending to integrate with the Hoory application for seamless authentication redirection.

Overview

When opening the Hoory login page with a callback query parameter, a callback will be triggered for third-party app authentication. Upon successful login, the request will be redirected to the callback URL, with additional parameters (token and account_id) appended to the callback query parameters.

Authentication URL

Here's the authentication URL format:

https://app.hoory.com/app/login?callback={redirect_url}

Replace {redirect_url} with the URL to which the user should be redirected after successful login.

Given redirect_url as https://example.com/anotherpage?param1=value1 the authentication login url will be:

https://app.hoory.com/app/login?callback=https%3A%2F%2Fexample.com%2Fanotherpage%3Fparam1%3Dvalue1

After login, the user will be redirected to:

https://example.com/anotherpage?account_id=3&token=eyJhY2Nlc3MtdG9rZW4iOiJyTG12cVBTTVIzQzh0bGRZZ1UzVkRnIiwidG9rZW4tdHlwZSI6IkJlYXJlciIsImNsaWVudCI6InlaOEFiRXRXVGM1Z29xOHdtSHlyWHciLCJleHBpcnkiOiIxNzAxMDkzMzEyIiwidWlkIjoibWFzb3VkQGhvb3J5LmNvbSJ9&param1=value1

account_id is an integer identifying the user account, and token is a base64-encoded JSON object. Upon decoding token, it reveals parameters useful for API authentication:

• access-token
• token-type
• client
• expiry
• uid

Additional Query Parameters

Feel free to add additional query parameters to your callback URL for restoring your application state or information tracking. The Hoory login redirect will retain these parameters alongside token and account_id in the redirected URL.

For instance, param1 parameter added to callback url and appended to the redirected url.

Token

The token appended to your callback URL is a base64-encoded string. When decoded, it transforms into a JSON object string containing essential authentication information. This JSON object holds keys such as access-token, token-type, client, expiry, and uid, all crucial for making authenticated API requests.

Here is an example of a decoded token:

{
  "access-token": "rLmvqPSMR3C8tldYgU3VDg",
  "token-type": "Bearer",
  "client": "yZ8AbEtWTc5goq8wmHyrXw",
  "expiry": "1701093312",
  "uid": "[email protected]"
}

Making a Request

After decoding the token, include uid, client, token-type, and access-token in your request headers to authenticate API requests.

Below is an example of demonstrating how to make a request to create an inbox:

cUrl

curl --location '{endPoint}' \
--header 'access-token: {access_token}' \
--header 'token-type: {token_type}' \
--header 'client: {client}' \
--header 'uid: {uid}' \

fetch

var headers = new Headers();
headers.append("access-token", accessToken);
headers.append("token-type", tokenType);
headers.append("client", client);
headers.append("uid", uid);

var formdata = new FormData();

var requestOptions = {
  method: 'POST',
  headers: headers,
  body: formdata,
  redirect: 'follow'
};

fetch(endPoint, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Axios

const axios = require('axios');

let config = {
  method: 'post',
  url: endPoint,
  headers: { 
    'access-token': accessToken, 
    'token-type': tokenType, 
    'client': client, 
    'uid': uid,  
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Create New Inbox Example

curl --location 'https://app.hoory.com/api/v1/accounts/{account_id}/inboxes' \
--header 'access-token: {access_token}' \
--header 'token-type: {token_type}' \
--header 'client: {client}' \
--header 'uid: {uid}' \
--form 'name="my_new_inbox_name"' \
--form 'greeting_enabled="false"' \
--form 'greeting_message=""' \
--form 'channel[type]="web_widget"' \
--form 'channel[website_url]="my_inbox_domain.com"' \
--form 'channel[widget_color]="#009CE0"' \
--form 'channel[welcome_title]=""' \
--form 'channel[welcome_tagline]=""'

For more information on API routes, please refer to the API documentation.

Validate Token

To check the token validity, send a request to the following endpoint:

http://app.hoory.com/auth/validate_token

This endpoint will return a wealth of user account information as a JSON object. Below is an example of the data structure you can expect in response when token is valid:

{
    "payload": {
        "success": true,
        "data": {
            "access_token": "...",
            "account_id": 1234,
            "available_name": "...",
            "avatar_url": "...",
            "confirmed": true,
            "display_name": null,
            "message_signature": null,
            "email": "...",
            "id": 186,
            "inviter_id": null,
            "name": "...",
            "provider": "email",
            "pubsub_token": "...",
            "role": "administrator",
            "ui_settings": {
                "rtl_view": false,
                "show_secondary_sidebar": true,
                "conversation_display_type": "expanded",
                "previously_used_sidebar_view": true
            },
            "uid": "...",
            "type": null,
            "accounts": [
                {
                    "id": 1234,
                    "name": "...",
                    "status": "active",
                    "active_at": "2023-09-28T08:54:30.556Z",
                    "role": "administrator",
                    "availability": "online",
                    "availability_status": "offline",
                    "auto_offline": true
                }
            ],
            "created_at": "2023-08-02T12:10:13.276Z"
        }
    }
}

And this response in case of using an invalid token:

{
    "success": false,
    "errors": [
        "Invalid login credentials"
    ]
}