Authorize your client application: Runtime

All client applications must provide a valid access token to be able to access the ASR, NLU, Dialog, and TTS runtime services as well as the runtime call logs.

Client Credentials flow

In particular, the runtime environment uses the OAuth 2.0 Client Credentials flow, as shown in this diagram:

1. The client application requests an access token from the Nuance authorization server, providing the client ID and client secret using the HTTP Basic authentication scheme. See Request an access token for an example.
2. The Nuance authorization server 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 authorizes the request by inspecting the access token; if the token is valid, it returns the Mix resource.

To enable authorization 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. Navigate to the App ID tab for your application:
   1. In the Mix dashboard, click the Manage tab.
   2. From the menu on the left, select Applications.
   3. Select the application.
   4. Click the settings icon .
   5. Click the App ID tab.
2. Click Add a new client.
3. In Add a new client, specify a client name and click Create.

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

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. Navigate to the App ID tab for your application:
   1. In the Mix dashboard, click the Manage tab.
   2. From the menu on the left, select Applications.
   3. Select the application.
   4. Click the settings icon .
   5. Click the App ID tab.
2. Click the arrow beside the client name to show the client details.
3. Click Delete Client.
4. Click Delete to confirm.

Generate the client secret

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

• Region: Region where the application config is deployed.
• App ID: ID for your application.
• One or more Client Names: Clients that can access the runtime services.

For example:

To generate the client secret for a client ID:

1. Navigate to the App ID tab for your application:
   1. In the Mix dashboard, click the Manage tab.
   2. From the menu on the left, select Applications.
   3. Select the application.
   4. Click the settings icon .
   5. Click the App ID tab.
2. Click the arrow beside the client name to show the client details.
3. Click Generate Client Secret.

The client secret is generated.

Specifying the client ID in your app

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 (that is, :), 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_company_com_20190919T190532%3Ageo%3Aqa%3AclientName%3Adefault"
$ 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 or if it has become compromised.

To regenerate the client secret:

1. Navigate to the App ID tab for your application:
   1. In the Mix dashboard, click the Manage tab.
   2. From the menu on the left, select Applications.
   3. Select the application.
   4. Click the settings icon .
   5. Click the App ID tab.
2. Click the arrow beside the client name to show the client details.
3. Click Regenerate Client Secret.
4. To regenerate the client secret, click “I understand, Regenerate Client Secret.”

Request an access token

To request an access token from the Nuance authorization server, you need this information:

When requesting an access token, the Nuance authorization server returns:

• The access token
• The token expiration (provided as the number of seconds after which the token will expire)
• The scope
• The token type (always set to bearer)

This example shows a sample token request using curl:

$ export CLIENT_ID="appID%3ANMDPTRIAL_alex_smith_company_com_20190919T190532%3Ageo%3Aqa%3AclientName%3Adefault"
$ 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"])'`"

Notice:

• The curl command uses Python to parse the response received from the Nuance authorization server and extract the token only.
• Note that the colons in the Client_ID are escaped (using %3A instead of :) so that the curl command can be split correctly.

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:

• Expect that, in rare cases, the token may become invalid or expire before the expected expiration time
• Be able to renew the token and retry the request

Nuance recommends reusing the access token until it expires. The expected token expiration validity period is returned in the token response, as shown above.

Accessing a runtime service

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

• URL of the service
• Access token
• URN of application configuration

URL of the service

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

• ASR: asr.api.nuance.com:443
• NLU: nlu.api.nuance.com:443
• Dialog: dlg.api.nuance.com:443
• TTS: tts.api.nuance.com:443
• NR: nr.api.nuance.com:443

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

There are two types of URNs: URNs for resources, and URNs for wordsets.

Mix.asr DLM, Mix.nlu model, and Mix.dialog resource URNs

You specify the URN for the Mix.asr DLM, Mix.nlu model, and Mix.dialog resource to load in your service gRPC API.

A URN has this pattern:

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

ASR and NLU wordset URNs

urn:nuance-mix:tag:wordset:lang/names-places/cities_wordset/eng-USA/mix.asr

Related topics

• Runtime APIs: Quick Reference