NAV Navbar

Obtain authentication for services

Nuance Mix uses the OAuth 2.0 protocol for authentication. All client applications must provide an access token to be able to access the ASR, NLU, Dialog, and TTS runtime services.

The following diagram summarizes the authentication process in Mix.

Authentication process

  1. The client application requests an authentication grant from the Mix authentication service, providing the client ID and client secret.
  2. The Mix authentication service generates and returns the access token.
  3. The client application sends a request to one of the Mix runtime services, providing the access token.
  4. The Mix runtime service authenticates the request by inspecting the access token; if the token is valid, it returns the Mix resource.

To enable authentication in your client application:

  1. Create a client ID. (Optional; you can use the default client ID if preferred.)
  2. Generate the client secret for a client ID; the client secret is required to request an access token.
  3. Request an access token.
  4. Specify the access token in your client application.

Create a client ID

By default, a single client ID is available for an App ID when you create a project, with a client name of default.

You can create additional client IDs as required.

To create a client ID:

  1. In Mix.dashboard, click Applications.
  2. Select the application.
  3. Click the App ID tab.
  4. Click Add a new client.
  5. In Add a new client, specify a client name and click Create.

The client is added to the App ID tab. For example:

Secret generation icon

You can now generate the client secret for this client ID and use it to access a runtime service.

Delete a client ID

You can delete client IDs if they are no longer required. Note that you need at least one client ID per App ID.

To delete a client ID:

  1. In Mix.dashboard, click Applications.
  2. Select the application.
  3. Click the App ID tab.
  4. Click the arrow beside the client name to show the client details.
  5. Click Delete Client.
  6. Click Delete to confirm.

Generate the client secret

You generate the client secret from the App ID tab. This tab contains the following information:

For example:

Secret generation icon

To generate the client secret for a client ID:

  1. In Mix.dashboard, click Applications.
  2. Select the application.
  3. Click the App ID tab.
  4. Click the arrow beside the client name to show the client details.
  5. Click Generate Client Secret.

The client secret is generated. Save this client secret somewhere safe, as you will not be able to access it again from Mix.dashboard.

Note: Only application owners are allowed to generate client secrets.

Specifying the client ID in your application

The client ID is composed of the string appID: followed by a unique ID. When specifying the client ID, you may need to escape the colons in the client ID (i.e., :), depending on how you are passing the client ID in your application.

For example, when using the curl command, which already uses a colon in the user option (-u), you need to replace the colon with %3A. For example:


$ export CLIENT_ID="appID%3ANMDPTRIAL_alex_smith_nuance_com_20190919T190532%3Ageo%3Aqa%3AclientName%3AScriptUser"
$ export SECRET="riAbk888CC2B.97D7eUklVe6pD"
$ export TOKEN="`curl -s -u "$CLIENT_ID:$SECRET" ... 

Regenerate the client secret

You may need to regenerate the client secret for a client ID if, for example, you lose it of if it has become compromised.

To regenerate the client secret:

  1. In Mix.dashboard, click Applications.
  2. Select the application.
  3. Click the App ID tab.
  4. Click the arrow beside the client name to show the client details.
  5. Click Regenerate Client Secret.
  6. To regenerate the client secret, click "I understand, Regenerate Client Secret."

Request an access token

To request an access token from the Mix authentication service, you need the following information:

Name Description
grant_type Always set this to client_credentials.
scope Scope for the client credentials grant. Enter one of the following: asr, nlu, dlg, tts. You can also request a grant for more than one service by separating the scopes with a space. For example, for all the services, specify asr nlu tts dlg; for TTS and Dialog, specify tts dlg.
client_id Specify the client ID. For example: appID:NMDPTRIAL_alex_smith_nuance_com_20190919T190532. See Specifying the client ID in your application for details.
client_secret Enter the client secret generated from Mix.dashboard for this client ID.
URL of the Mix Authentication Service This is: https://auth.crt.nuance.com/oauth2/token

When requesting an access token, the Mix Authentication Service returns:

The following code shows a sample token request using curl:

Notes:


$ export CLIENT_ID="appID%3ANMDPTRIAL_alex_smith_nuance_com_20190919T190532%3Ageo%3Aqa%3AclientName%3AScriptUser"
$ export SECRET="riAbk888CC2B.97D7eUklVe6pD"
$ export TOKEN="`curl -s -u "$CLIENT_ID:$SECRET" "https://auth.crt.nuance.com/oauth2/token" -d 'grant_type=client_credentials' -d 'scope=asr' | python -m json.tool |  python -c 'import sys, json; print(json.load(sys.stdin)["access_token"])'`"

Save the token returned in a safe place, as you will need it to access the runtime services.

Access token lifetime

Currently, the access token expires after 15 minutes.

When you receive a token, you also receive the lifespan of the token, in seconds, in the expires_in field. For example:

{"access_token":"eyJhbG*****3UmrGG7ro","expires_in":899,"scope":"dlg",
"token_type":"bearer"}

This is the value that you should use to estimate the validity of the token. As a good practice, Nuance recommends that your client application should:

Accessing a runtime service

To access a runtime service from your client application, you need the following information:

URL of the service

This is the URL of the Mix runtime environment where the application is deployed. This is one of the following:

You specify this URL when creating a gRPC channel.

Access token

You specify the token obtained from the Mix access token service as the credentials when creating a gRPC channel.

When using a REST API, specify the access token as a bearer token in the request header.

URN

You specify the URN for the resource to load in your service gRPC API. A URN has the following pattern:

urn:nuance-mix:tag:model/context_tag/service(?=language=language)

Where:

For example, to load the resource for the American English coffee_app application configuration, specify the URN as follows:

Service URN
Mix.asr urn:nuance-mix:tag:model/coffee_app/mix.asr?=language=eng-USA
Mix.nlu urn:nuance-mix:tag:model/coffee_app/mix.nlu?=language=eng-USA
Mix.dialog urn:nuance-mix:tag:model/coffee_app/mix.dialog