API token authentication

Nuance Customer Engagement API (CEAPI) supports the OAuth 2.0-based authorization framework for application-level tokens. OAuth 2.0 provides authorization based on the Client Credentials Grant Flow of the OAuth 2.0 specification.

The list of steps required to access the API using OAuth 2.0-based authorization are as follows:

  • Client registers their application with Nuance
  • Client application requests the access token using the Authorization Server
  • Client application uses the access token in every API request

Register the application

Clients may request application registration with Nuance by contacting their Client Services Manager (CSM). The CSM will register your application with the Nuance System Team.

The clientId identifies your application and builds login URLs.

The clientSecret authenticates the identity of your application. It must be kept private between the application and the API.

Note: The client is responsible for storing the clientID and the clientSecret securely. If this information is compromised, you must request a lock on the account and a new registration with your CSM.

Obtain an access token

The client application must connect to the OAuth server using the clientID and clientSecret provided by Nuance. The clientId and clientSecret must be formatted properly for transmission. Formatting requires you to concatenate the clientId, a colon (:), and the clientSecret into a single string as follows:

clientId:clientSecret

The resulting string should be base-64 encoded and inserted into the Authorization Header in the following format:

Authorization: Basic [Base-64 encoded string]

Request URL

https://{auth.nuance.com}/oauth-server/oauth/token

Where {auth.nuance.com} is the domain name. Domain names differ for each client.

Response format: JSON

Sample request for obtaining an access token

POST https://{auth.nuance.com}/oauth-server/oauth/token

Form data

client_id:"ceapiId"
grant_type:"client_credentials"

Where:

  • client_id: Provided by the CSM when the client application was registered with Nuance.
  • grant_type: Should be client_credentials for the CEAPI. When Nuance adds other APIs, this value may be differ.

Request header

Host: auth.nuance.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic Y2VhcGlDbGllbn...

Note: Examples (token strings such as the Bearer token and access token, below) have been truncated for brevity.

Sample response from Nuance

{
   access_token: "Y2VhcGlDbGllbn...",
   token_type: "bearer",
   expires_in: 59,
   scope: "read write",
   sites: ["154", "306"],
   jti: "a1bc11d1-11a1-1111-b111-d1111e1f11f1"
}

Where:

  • access_token: Must be included in all API data requests.
  • token_type: Value is “bearer” and must be included in all API data requests.
  • expires_in: Indicates the expiration time of the token in seconds. The client app should monitor this value and request a new token whenever necessary. If the app uses an expired token the server will return a code 401 “Access Token Expired” message.
  • scope: Indicates the access permissions for this token. If a disallowed action is performed, the server will return an error.
  • sites: Indicates the site IDs that are valid for this token. If the request tries to access a site that is not on the list, the server will return an error.
  • jti: ID for the access token used for tracking purposes. Clients can ignore this value.

Use the access token in an API request

The access token must be present in every API data request. It must be in the authorization header in the following format:

Authorization: Bearer [access token]

Sample API Request with bearer token 

POST https://{api.nuance.com}/engagementAPI/v2/customer/agentAvailability?businessUnitID=22&output=JSON&siteID=306

Where {api.nuance.com} is the domain name. Domain names can vary for each client.

Request header

Host: {api.nuance.com}
Authorization: Bearer eyJhbGciOiJSUz...

Sample success response from Nuance

200 OK