Skip to main content
ASAPP integrates with your APIs to provide customers and agents with richer and more personalized interactions. ASAPP accomplishes this by making real-time backend calls to customer APIs, providing customers with current, up-to-date information. Customers must expose relevant APIs securely for ASAPP to make server-to-server calls.

​
Authentication

Customers should secure their APIs with authentication mechanisms, addressing both Customer Authentication and API Authentication.

​
API Authentication on behalf of the User

ASAPP leverages customers’ existing mechanisms for authenticating their customers, which should ideally remain consistent across different channels. Systems should issue identifiers with short expiration times while allowing for good user experience without requiring customers to authenticate multiple times during a session.
  • Cookie-based Authentication: Users post login credentials to the customer’s server and receive a signed cookie. The server stores the cookie and places a copy in the browser for use in subsequent interactions during the session. However, teams typically prefer token-based approaches where possible.
  • Token-based Authentication: Users post login credentials to the customer’s server and receive a signed JSON Web Token (JWT). The server does not store this token, making all interactions fully stateless. All client requests include the JWT, which only the server can decode to authenticate every request. For more information on generating and signing JSON Web Tokens, refer to https://jwt.io/.
API Endpoint: POST /customer_authenticate Request 
curl -X POST https://api.example.com/auth/customer_authenticate \
-H 'cache-control: no-cache' \
-d 'username=<username>&password=<password>'
Response 
{
  "issued_at" : "1570733606449",
  "JWT" : "<JWT>",
  "expires_in" : "28799"
}
ASAPP requires direct access to the “customer_authenticate” API to retrieve JWTs/cookies programmatically for testing.

​
Communicating Customer Identifier with ASAPP

Customers can implement any mechanism to authenticate their users, as long as they can pass the identifier (cookie, JWT, etc.) to ASAPP. The methods for passing this value to ASAPP depend on the chat channel used: Web, iOS, or Android.

​
Customer Identifier Requirements

ASAPP uses this customer identifier as a pass-through value by including it as an HTTP Header or in the request body when requesting customer data from backend APIs. Since the Customer Identifier is the only data ASAPP uses to identify users, it must adhere to the following requirements:
  • Unique: ASAPP will associate every customer chat with this id allowing ASAPP to tie chats from different channels into one single conversation. It is imperative that the Customer Identifier be unique per customer.
  • Consistent: The Customer Identifier should remain consistent so that even if the customer returns after a significant amount of time, we are able to identify the customer.
  • Opaque: The Customer Identifier by itself should not contain any customer Personally Identifiable Information (PII). It should be hashed, encoded and/or encrypted so that when used by itself, it is of no value.

​
API Authentication using System-level Credential

Customers can secure backend APIs by restricting client access to specific resources for limited time periods. Teams can implement this using various mechanisms like OAuth 2.0, API Keys, or System Credentials. This section details OAuth using a Client Credentials Grant, which works well for server-to-server communication.

​
Client Credentials Grant

In this mechanism, the client sends a HTTP POST request with the following parameters in return for an access_token.
  • grant_type
  • client_id
  • client_secret
API Endpoint: POST /access_token Request 
curl -X POST https://api.example.com/oauth/access_token?grant_type=client_credentials 
\
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id=<client_id>&client_secret=<client_secret>'
Response 
{
  "token_type" : "Bearer",
  "issued_at" : "1570733606449",
  "client_id" : “<client_id>”,
  "access_token" : "<access_token>",
  "scope" : "client_credentials",
  "expires_in" : "28799"
}

​
API Authorization

Customers can also use API keys to provide authorization to specific APIs. API keys are passed in the HTTP header along with the authentication token. API Endpoint: POST /getprofile Request 
curl -X POST https://api.example.com/account/getprofile
-H 'Authorization: Bearer <access_token>' \
-H 'customer-auth: JWT <JWT>' \
-H 'content-type: application/json' \
-H 'api-key: <api_key>' \