Authentication

OAuth Authentication

OAuth2 is a secure way to authenticate your API requests, allowing access to your account data without sending sensitive information such as your email and password. There are different OAuth flows depending on the type of API request.

Note that when generating an access token, the API request must begin with your platform's specific domain. Here's how it varies:

• dash11.comm100.io: https://dash11.comm100.io/
• dash12.comm100.io: https://dash12.comm100.io/
• dash13.comm100.io: https://dash13.comm100.io/
• dash15.comm100.io: https://dash15.comm100.io/
• dash17.comm100.io: https://dash17.comm100.io/

How to Get the Access Token

To access protected resources using OAuth authentication, you need to obtain an access token. There are three primary methods for obtaining an access token:

1. Password Grant (Not Recommended, Deprecated)
2. Authorization Code Grant (Recommended)
3. Refresh Token Grant (To Get a New Access Token)

Each method is designed for different use cases and comes with its own steps. Here's an overview of each:

Password Grant

The Password Grant is used when the application exchanges the user's username and password for an access token. However, it is considered less secure because it involves sending sensitive credentials (like the user’s password) to the authorization server. This method is generally discouraged in favor of more secure approaches like Authorization Code Grant. In fact, OAuth 2.0 Security Best Practices suggest avoiding this grant type, and it will be removed in the upcoming OAuth 2.1 update.

Steps to Get the Access Token Using Password Grant:

1. Gather Required Information
   • client_id: Obtain this from your OAuth client settings in the Comm100 Control Panel.
   • email and password: The credentials of the agent account.
2. Make a POST Request to the /oauth/token/ endpoint, endpoint, including the required parameters:
   • grant_type=password
   • email={agent_email}
   • password={agent_password}
   • client_id={client_id}

Sample Request Using cURL:

curl https://dash11.comm100.io/oauth/token \
-X 'POST' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'email={agent_email}' \
--data-urlencode 'password={agent_password}' \
--data-urlencode 'client_id={client_id}'

Response:
If the request is successful, you will receive a response containing the access_token, refresh_token, and other details.

 {
       "access_token": "eyJhbGciOiJodHRwOi8vd3d3...",
       "refresh_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8y...",
       "token_type": "bearer", 
       "expires_in": 43200, 
  }

Authorization Code Grant

The Authorization Code Grant is the most secure and commonly used OAuth flow. It involves the user being redirected to an authorization server to log in and authorize the application to access their resources. Once the user approves, the application can exchange the authorization code for an access token.

This flow provides greater security because the user's credentials are never directly exposed to the application.

Steps to Get the Access Token Using Authorization Code Grant:

1. Redirect the User to the authorization endpoint /oauth/authorize. The user logs in and approves the request.
2. After the user approves the request, the server will redirect the user back to your application’s redirect_uri with an authorization code.
3. Exchange the authorization code for an access token by sending a POST request to the /oauth/token endpoint.

Sample Request Using cURL (to obtain authorization code):

curl https://dash11.comm100.io/oauth/authorize \
-X 'GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'response_type=code' \
--data-urlencode 'redirect_uri=https%3A%2F%2Fdash11.comm100.io%2Fagentconsole%2Fauthed' \
--data-urlencode 'code_challenge=xxxxxx' \
--data-urlencode 'code_challenge_method=S256' \
--data-urlencode 'siteId=10000'

Once the authorization code is received, you can exchange it for an access token.

Sample Request to Exchange Authorization Code for Access Token:

curl https://dash11.comm100.io/oauth/token \
-X 'POST' \
-H 'Content-Type: x-www-form-urlencoded' \
-D '{
    "client_id": "xxx",
    "code_verifier": "xxxxxx",
    "grant_type": "authorization_code",
    "code": "eyJhbGciOiJodHRw..",
    "redirect_uri":"https://dash11.comm100.io/agentconsole/authed"
}'

Response:

{
    "access_token": "eyJhbGciOiJodHRwOi8vd3d3...",
    "refresh_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8y...",
    "token_type": "Bearer",
    "expires_in": 43200
}

Refresh token

Once you have an access_token and it expires, you can use the refresh_token to request a new access token. This process is more secure than having to repeatedly ask the user to re-authenticate.

Steps to Get the Access Token Using Refresh Token:

1. Obtain your refresh_token from a previous request.
2. Send a POST request to the /oauth/token endpoint with the grant_type=refresh_token.

Sample Request Using cURL:

curl https://dash11.comm100.io/oauth/token \
-X 'POST' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'refresh_token={refresh_token}' \
--data-urlencode 'client_secret={client_secret}'

Response:

{
    "access_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxctbW......",
    "refresh_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZ.....",
    "token_type": "Bearer",
    "expires_in": 43200
}

Refer to this Guide on How to call API with Oauth authentication

API Key Authentication

To authenticate API requests, you must include your email and API key. Authentication is done via HTTP Basic Auth, where your email is the username, and the API key is the password. While this method is still supported, we recommend using OAuth authentication for better security.

Important: When using the API key for authentication, ensure that you include the siteId parameter.

For example:
GET https://api11.comm100.io/v4/livechat/campaigns?siteId=10000

For detailed instructions on how to get your API key and use it for authentication, refer to the How to get API Key and call API with API Key authentication.