Authentication

Access to the API Service is session-based. Authentication is accomplished using HTTPS combined with secure cookies.

To authenticate and create a session:

  1. Make a POST request to the following URL using the parameters in the table.

    https://api.<<clientname>>.digital.nuance.com/j_spring_security_check

  2. Capture the cookie that is returned when you successfully authenticate.

  3. Use the cookie in subsequent requests to the API service.

To close a session, make a GET request, passing in the session cookie to the following URL:

http://api.<<clientname>>.digital.nuance.com/logout

Parameter key

Value

Description

j_username

<username>

Specify the username of the API Service requester

j_password

<password>

Specify the password of the API Service requester

submit

Login

Specify the literal string Login to login

Example

Authentication

curl -c cookie.txt -d
"j_username=foo%40inq.com&j_password=pass123&submit=Login" https://api.<<clientname>>.digital.nuance.com/j_spring_security_check

Make one or more queries. You must use the cookie from above.

Sample Request

curl -b cookie.txt  https://api.nuance.com/...

Logout

curl -b ./cookie.txt https://api.nuance.com/logout

Note: The same session cookie can be used for multiple chat sessions.

API requests per second (throttling)

The number of requests per second that a user can make to the API is unlimited by default. You can “throttle” individual user accounts by placing a limit on the number of requests allowed per second. To do this, you must change the Number of Requests Allowed per Second value for a user account in the Portal interface.

Where Number of Requests Allowed per Second is set to:

  • Null, the number of queries allowed per second is unlimited (Default)

  • Zero, the user account cannot send queries to the API

  • 1, the user account can send 1 query per second to the API

  • 2, the user account can sent 2 queries per second to the API

To change this value per user, from the Portal interface choose Admin→User Management→Edit User and select the API Settings tab. This action requires Administrative privileges.

Accessing Reporting API via OAuth token

Here is a summary list of the steps required to access the Reporting API using OAuth:

  1. Create a new user in the oauth_client_details table.

  2. Send a POST request to the Nuance OAuth Server from your application.

  3. Extract the token from the JSON response and use it to send the request to the APIService.

  4. (Optional) Refresh token in cases where the access token has expired.

1. Create new user

Create a new user in the oauth_client_details table as follows:

INSERT INTO configuration.oauth_client_details (client_id, resource_ids, 
client_secret, scopes, authorized_grant_types, web_server_redirect_uri, 
access_token_validity_sec, refresh_token_validity_sec,  
autoapprove_scopes, locked, all_site_access) VALUES ('apiClientId', 
'apiService', 'apiClientSecret', 'read,write,historic,realtime', 
'password,refresh_token', '', 900, 9000, '', 0, 1);

Where values apiClientId and apiClientSecret are to be replaced according to security needs.

2. Send POST request

Send a POST request to the Nuance OAuth Server from your application, specifying in the Authorization header your application credentials (values for apiClientId:apiClientSecret) using base64 encoding, as per the example below.

POST https://{auth.nuance.com}/oauth-server/oauth/token
Authorization: Basic YXBpQ2xpZW50SWQ6YXBpQ2xpZW50U2VjcmV0 
Cache-Control: no-cache 
Content-Type: application/x-www-form-urlencoded
client_id=apiClientId&grant_type=password&username=api&password=1

Where:

client_id

Application id from oauth_client_details table

grant_type

Only the password grant type is supported

username

Name of user from the users table on whose behalf the request is being sent. This user should exist in the users table and have access to the Reporting API.

password

Password of the user on whose behalf the request for a token is being sent.

Example response from Nuance OAuth Server:

POST https://{auth.nuance.com}/oauth-server/oauth/token
 
HTTP/1.1 200 OK 
Server: nginx/1.14.0 (Ubuntu) 
Date: Tue, 03 Nov 2020 17:12:01 GMT 
Content-Type: application/json;charset=utf-8
Content-Length: 3603
Connection: keep-alive 
Vary: Origin 
Vary: Access-Control-Request-Method 
Vary: Access-Control-Request-Headers 
Strict-Transport-Security: max-age=31536000; includeSubDomains 
Cache-Control: no-store 
Pragma: no-cache 
X-Content-Type-Options: nosniff 
X-XSS-Protection: 1; mode=block 
X-Frame-Options: DENY 
 
{ 
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",  
"token_type": "bearer", 
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",  
"expires_in": 899, 
"scope": "read write historic realtime", 
"sites": [ 
"306"
], 
"jti": "189243a7-7b0b-4fe9-8f20-a28472b5b198"
}

3. Extract token from JSON response

Extract the token from the JSON response and use it to send the request to the APIService.

Example:

GET https://api.nuance.com/v3/transcript/historic?filter=engagementID=123&site=306&returnFields=engagementID&encrypted=false&output=xml
Accept: */* 
Cache-Control: no-cache 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Connection: close

4. Refresh token when needed

If the access token expires, a new one can be requested via the refresh token. For a refresh_token, the grant_type is required.

Example:

POST https://{auth.nuance.com}/oauth-server/oauth/token 
Authorization: Basic YXBpQ2xpZW50SWQ6YXBpQ2xpZW50U2VjcmV0 
Cache-Control: no-cache 
Content-Type: application/x-www-form-urlencoded   
grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Note: Examples (token strings) have been truncated for brevity.