0. Authentication & Authorization

Number of APIs: 1

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.

Client Registration

Please check the following document for API client access here

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 'appkey:your-application-key' -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": "****....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "*****....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

Failures
- Bad Request (400) - granttype or clientid 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 'appkey:your-application-key' -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": "*****....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "*****....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

Failures
- Bad Request (400) - granttype or clientid 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 'appkey:your-application-key' -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": "*****....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "*****....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

Failures
- Bad Request (400) - granttype, clientid 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 accesstoken_ proves the identify of the caller at the Resource Server and enforce access control. Include the accesstoken_ in the Authorization header and appkey as a header parameter to a REST API request as follows.

Authorization: Bearer *****....
appkey: oshbdchmcm....

A&A Failure Codes:

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

Acquire Access Token (Refresh Token) POST https://{{axpAPIDomain}}/api/auth/v1/{{accountId}}/protocol/openid-connect/token