Service account: OAuth 2.0 Client Credentials flow

Use the service account and OAuth 2.0 Client Credentials flow for machine-to-machine communication, such as running offline Mix.api scripts.

The OAuth 2.0 Client Credentials grant type flow works as follows:

Authorization process

  1. The client application requests an access token from the Nuance authorization server, providing the service credentials (client ID and client secret) using the HTTP Basic authentication scheme.
  2. The Nuance authorization server generates and returns the access token.
  3. The client application sends a Mix.api request, providing the access token.

Implement the Client Credentials flow in your client application

To enable authorization in your client application:

  1. Obtain a service account.
  2. Generate service credentials.
  3. Request an access token.
  4. Specify the access token in the client application.

Obtain a service account

Access to the OAuth 2.0 Client Credentials flow must be enabled by Nuance. Please contact your Nuance representative to obtain a service account.

Nuance recommends that you create a single user—for example, service_user@organization.com—to manage service credentials. The following section provides suggestions on managing and using this account in your organization.

Service credentials sample implementation

Sign up to Mix and create a single service account—for example, service_user@organization.com—with a functioning email address. Ask your Nuance representative to provision the account with the following roles:

  • service_user global role
  • owner of the company’s organization(s)

When the account is enabled, log in to Mix with this account and generate a set of service credentials for this user. Store the client secret in the key vault of the company and share it only when integration scripts need to use this account. This approach ensures the security of the assets accessed by the service account when logged into the platform.

In addition to being the service account user for machine-to-machine communication, this account has the organization owner role, so it can be used to manage user roles and permissions in the organization.

Generate service credentials for Mix.api

You can create a new client ID and credentials to use as a service account.

To generate service credentials for Mix.api:

  1. Log in to Mix using the service account.
  2. In the Mix dashboard, click the user account name and select Profile.
  3. In the Service Credentials area, click Create Service Credentials.

Generate service credentials for Mix.api

This creates a client ID for the service account.

To generate the client secret for the service account:

  1. Navigate to the Service Credentials area.
  2. 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 your profile page.

Request an access token

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

Name Description
grant_type Always set this to client_credentials.
scope Scope for the client credentials grant. Enter: mix-api
client_id Specify the service client ID. For example: mix-api-client:e9a7e628-fa6a-4a40-b4c1-25ac4e7c65fc. See Specifying the client ID in your application for details.
client_secret Enter the client secret that you generated for the service client ID.
URL of the Nuance authorization server This is: https://auth.crt.nuance.com/oauth2/token

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)

The following code shows a sample token request using curl. Note that:

  • 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.
export CLIENT_ID="mix-api-client%3Ae9a7e628-fa6a-4a40-b4c1-25ac4e7c65fc"
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=mix-api" | 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.

Specify the 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.

Specify the client ID in your application

The client ID for Mix.api is composed of the string mix-api-client: followed by a unique ID. When specifying the client ID, you may need to escape the colon (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="mix-api-client%3Ae9a7e628-fa6a-4a40-b4c1-25ac4e7c65fc"
export SECRET="riAbk888CC2B.97D7eUklVe6pD"
export TOKEN="`curl -s -u "$CLIENT_ID:$SECRET" ...