How to Authenticate with Avaya Experience Platform™ APIs

Introduction

The Avaya Experience Platform™ A&A Service provides the following capabilities:

• Authenticate users locally or with enterprise IDPs via OIDC and SAML.
• Authenticate clients or applications using OAuth2 Access Tokens passed as Bearer token in the request.
• Provide a means to applications to authorize users and other applications by virtue of the roles and permissions present in the Access Token.

This document describes the APIs supported in order to meet the capabilities described above. Before that, a few terminologies:

The Avaya Experience Platform™ A&A Service (henceforth called A&A) facilitates both authentication and authorization. The authentication is not done very frequently (often only at startup or when trying to refresh tokens). After successfully authenticating itself and (optionally) a user, a client is issued an “Access Token” which is then presented to the resource server along with each request. The resource server does not authenticate the entity making the request, but validates the token and ensures that the token indicates that the requested operation may be invoked by the client holding the token.

Supported OAuth2 Flows

OAuth 2.0 defines four grant types, which clients can use to request Access Tokens. For the current release, A&A supports three of them. A&A requires the client to authenticate itself with every one of these grant types, even those that additionally authenticate a user.

• Client Credentials (CC) Grant Type
  • This grant type only authenticates the client (not a user). It is generally useful for server-based applications that are not acting on the behalf of a particular user.
• Authorization Code (Code) Grant Type
  • This grant type authenticates both the client and the user. It is a redirect-based flow.
  • Your application does not handle the user’s credentials, instead of redirecting the user’s browser to A&A for validation of the user's credentials.
  • Once the user’s credentials have been validated by A&A, it redirects the browser back to your application with an authorization code, which your application then exchanges for an Access Token.
  • The benefit of this flow is that it enables SAML and OIDC based authentication with external IDPs.
  • This grant type is used to login a user to the Avaya Experience Platform™ Admin Portal and Agent Desktop.
• Resource Owner Password Credentials (ROPC) Grant Type
  • This grant type authenticates both the client and the user. It is NOT a redirect-based flow.
  • This flow is simpler than the Authorization Code Grant Type flow, but it is more limited as it does not allow for SAML and OIDC. In other words, it only works if user identities (Administrators, Agents, etc) are managed locally by Avaya Experience Platform™.
  • In this flow, the client passes its own credentials as well as the end-user's credentials in a single request and can obtain an Access Token after successful authentication of both entities.

Diagram of Avaya Experience Platform™ APIs Supported OAuth2 Flow

Here is a high-level overview of how Avaya Experience Platform™ APIs utilize an OAuth2 Flow to authenticate Avaya Experience Platform™ API use:

Client Registration

Clients need to be registered first before they can request Access Tokens - either for users or themselves.

OneCare ticket needs to be raised by following these steps:

1. Navigate to OneCare Portal and login using Avaya SSO
2. Select Avaya Cloud Solutions Support in the "View" field and then click on Avaya Experience Platform™ tile.

3. After Clicking Avaya Experience Platform, you will be displayed a page with Multiple Tiles. Select 'Client Access Request for AXP APIs' Tile.

   

4. A form will open on the right with multiple options. The Form will be pre-populated with Name and other details based on SSO. Select 1 option which is relevant from the Dropbox. The options and the steps for them are described in the sections below.

A. Requesting new Client Credentials & Application Key

Option applicable if the client credentials and application key both need to be generated.

5. The request needs the following information:
   • Subscription ID: Customer Subscription ID
   • Short Description: Client Secret and Application Key needed for client integration (e.g. custom chat connector)
   • Issue Description:
     • Client ID - A name (string) to uniquely identify the client. It can contain letters, numbers, and special character '-' (hyphen). It cannot contain any spaces. Client ID is not case sensitive. [Optional for this sub-category only]
     • Scope - Provide the name of the APIs that the client will invoke. The Avaya Experience Platform™ Administrator will use this information to set up the client with relevant roles and permissions.
     • Account: (Account name from Admin Account page)
     • Domain: (Domain name from Admin Account page)
     • Account ID: (Account ID from admin Account page, button "Copy Account ID" - this is a 6 digit alphanumeric string)
     • Environment: (e.g. Prod NA)

6. Click Submit to Create Ticket with Avaya
7. The ticket will then be redirected to the CloudOps team to start the provisioning.
8. Customers will receive an email from CloudOps with the requested details.

B. Requesting Application Key Only

Option applicable if the client credentials already exist and only the application key needs to be generated.

5. The request needs the following information:
   • Subscription ID: Customer Subscription ID
   • Client ID - A name (string) to uniquely identify the client. It can contain letters, numbers, and special character '-' (hyphen). It cannot contain any spaces. Client ID is not case sensitive. Please mention the existing Client ID here.** [Mandatory field for this sub-category]
   • Short Description: Application Key needed for client integration (e.g. custom chat connector)
   • Issue Description:
     • Scope - Provide the name of the APIs that the client will invoke. The Avaya Experience Platform™ Administrator will use this information to set up the client with relevant roles and permissions.
     • Account: (Account name from Admin Account page)
     • Domain: (Domain name from Admin Account page)
     • Account ID: (Account ID from admin Account page, button "Copy Account ID" - this is a 6 digit alphanumeric string)
     • Environment: (e.g. Prod NA)

6. Click Submit to Create Ticket with Avaya
7. The ticket will then be redirected to the CloudOps team to start the provisioning.
8. Customers will receive an email from CloudOps with the requested details.

C. Other

Option applicable for miscellaneous questions or any other information needed .

Acquiring Tokens

Shown below are examples of request/response for Generate Access Token

Client Credentials Grant

Request

curl -X POST https://REGION.api.avayacloud.com/api/auth/v1/{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id={clientId}&client_secret={secret}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type or client_id is invalid
  • Unauthorized (401) - secret is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "unauthorized_client",
    "error_description": "Invalid client secret"
}

Resource Owner Password Credentials Grant

Request

curl -X POST https://REGION.api.avayacloud.com/api/auth/v1//{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=password&client_id={clientId}&client_secret={secret}&username={userName}&password={userPassword}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type or client_id is invalid
  • Unauthorized (401) - secret is wrong.
  • Unauthorized (401) - username password combination is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "unauthorized_client",
    "error_description": "Invalid client secret"
}

Token Refresh

Request

curl -X POST https://REGION.api.avayacloud.com/api/auth/v1/{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=refresh_token&client_id={clientId}&client_secret={secret}&refresh_token={refresh_token}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type, client_id or refresh_token is invalid
  • Unauthorized (401) - secret is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "invalid_grant",
    "error_description": "Invalid refresh token"
}

Making an API Call

An access_token proves the identify of the caller at the Resource Server and enforce access control. Include the access_token in the Authorization header of a REST API request as follows.

Authorization: Bearer eyJhbGciOiJSUzI1....

A&A Failure Codes:

• Unauthorized (401) - Missing or Invalid token.
• Access Denied (403) - Token validation successful, but insufficient privileges.

Additional Resources

Avaya Learning Videos

How to Authenticate With Avaya Experience Platform™ APIs