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:
- 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.
- The Nuance authorization server generates and returns the access token.
- The client application sends a request to one of the Mix runtime services, providing the access token.
- 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:
- Create a client ID. (Optional. You can use the default client ID if preferred.)
- Generate the client secret for a client ID. The client secret is required to request an access token.
- Request an access token.
- 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:
- Navigate to the App ID tab for your application:
- In the Mix dashboard, click the Manage tab.
- From the menu on the left, select Applications.
- Select the application.
- Click the settings icon .
- Click the App ID tab.
- Click Add a new client.
- 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.
Warning:
If you delete a client ID, it is no longer available. Client applications using this client ID will no longer be able to access a runtime service.To delete a client ID:
- Navigate to the App ID tab for your application:
- In the Mix dashboard, click the Manage tab.
- From the menu on the left, select Applications.
- Select the application.
- Click the settings icon .
- Click the App ID tab.
- Click the arrow beside the client name to show the client details.
- Click Delete Client.
- 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:
- Navigate to the App ID tab for your application:
- In the Mix dashboard, click the Manage tab.
- From the menu on the left, select Applications.
- Select the application.
- Click the settings icon .
- Click the App ID tab.
- Click the arrow beside the client name to show the client details.
- Click Generate Client Secret.
The client secret is generated.
Note:
Save this client secret somewhere safe, as you will not be able to access it again from Mix dashboard. Nuance recommends that you follow best practices for keeping application credentials safe. Only application owners are allowed to generate client secrets.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.
Warning:
If you need to regenerate the client secret, be aware that this will have an impact on all existing client applications using the original client secret. They will no longer be able to access the runtime services. You will need to replace the client secret in all applications that use this client secret.To regenerate the client secret:
- Navigate to the App ID tab for your application:
- In the Mix dashboard, click the Manage tab.
- From the menu on the left, select Applications.
- Select the application.
- Click the settings icon .
- Click the App ID tab.
- Click the arrow beside the client name to show the client details.
- Click Regenerate Client Secret.
- 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:
Name | Description |
---|---|
grant_type |
Always set this to client_credentials . |
scope |
One or more scopes for client credentials grant. You can 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 nr ; for TTS and Dialog, specify tts dlg . For Mix.api authorization, see Authorization. |
client_id |
Specify the client ID. For example:appID:NMDPTRIAL_alex_smith_company_com_20190919T190532:geo:qa:clientName:default You can find the client_id in the Credentials tab. See also Specifying the client ID in your app. |
client_secret |
Enter the client secret generated from the Mix dashboard for this client ID. |
URL of Nuance authorization server | See Authorization URL for the URL to use in your geography. |
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.
Tip:
To implement OAuth2 authorization in your client applications, use an existing OAuth2 library available for your programming language. For a list of available libraries, see the OAuth 2.0 website .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.
Warning:
The application may be limited to a certain maximum number of active access tokens and the authorization service is subject to rate limits, as described in Rate limits. If limits are exceeded, the application may be refused a new access token and a 429 TOO_MANY_REQUESTS error code may be returned. Make sure to reuse access tokens until they expire to avoid these errors.Accessing a runtime service
To access a runtime service from your client application, you need this information:
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)
Where:
- context_tag is the Context Tag specified when creating an application configuration, for example,
A48_C643
orcoffee_app
. - service is one of
mix.asr
,mix.nlu
, ormix.dialog
. - language is the locale of the application configuration. For URNs, this is the 6-letter language code as documented in the Geographies section; for example,
eng-USA
. This applies to Mix.asr and Mix.nlu only.
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 |
You can find the URN for an application configuration in the Credentials tab.
ASR and NLU wordset URNs
URNs for the ASR and NLU wordsets have one of the following patterns, depending on the level of the wordset:
-
Application-level wordset:
urn:nuance-mix:tag:wordset:lang/context_tag/resource_name/language/service
-
User-level wordset:
urn:nuance-mix:tag:wordset:lang/context_tag/resource_name/language/service?=user_id=userId
Where:
- context_tag is the context tag name for this wordset. When you create the wordset, you can provide any context tag name. This name does not have to match the context tag of the companion Mix.asr DLM or Mix.nlu model.
- resource_name is the name of the wordset.
- service is one of
mix.asr
ormix.nlu
. - language is the locale of the wordset. For URNs, this is the 6-letter language code as documented in the Geographies section; for example,
eng-USA
. - userID is the unique identifier for the user.
For example, to upload the Mix.asr cities_wordset
application-level wordset, specify the URN as follows:
urn:nuance-mix:tag:wordset:lang/names-places/cities_wordset/eng-USA/mix.asr
Related topics
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.