Watson Machine Learning authentication

To be able to use IBM Watson Machine Learning interfaces such as the Python client, the REST API, or the CLI, you need to authenticate. This topic describes authentication methods for different products and interfaces.

Security overview

Refer to the section that describes your security needs.


These terms relate to the security requirements described in this topic.

  • An IAM token is an authentication token required to access IBM Cloud services.
  • VCAP credentials are needed for the Watson Machine Learning service instance. These credentials are created in the service credential section of the instance in IBM Cloud. They generate an API key.
  • API keys allow you to easily authenticate when using the Python client or APIs that can be used across multiple services. API Keys are considered confidential since they are used to grant access. Treat all API keys as you would a password since anyone with your API key can impersonate your service.



All of the examples below require you to look up your Watson Machine Learning service credentials.

See: Looking up credentials

In all of the examples below, the following fictional credentials are used:

apikey      : 123456789
instance_id : ABCDEFG
url         : https://HIJKL
username    : MNOPQRS
password    : TUVWXYZ

You must replace the fictional credentials with your own.




Python client

See: Watson Machine Learning Python client external link Your Python client must be 1.0.365 or later.

To create an instance of the Watson Machine Learning Python client object, you need to pass your credentials.

wml_credentials = {
    "apikey"      : "123456789",
    "instance_id" : "ABCDEFG",
    "url"         : "https://HIJKL",

client = WatsonMachineLearningAPIClient( wml_credentials )

Note that IBM Cloud Pak for Data also requires you pass username and password as part of your credentials. In that case, your credentials would be:

wml_credentials = {
    "apikey"      : "123456789",
    "instance_id" : "ABCDEFG",
    "url"         : "https://HIJKL",
    "username"    : "MNOPQRS",
    "password"    : "TUVWXYZ"
client = WatsonMachineLearningAPIClient( wml_credentials )

Watson Studio Local

Authenticating the Python client on Watson Studio Local:

  • apikey does not apply and is not used
  • instance_id must be set to: “icp”. The exception is if you are running Watson Studio Local on OpenShift. In that case, the instance_id should be set to “openshift”.
  • url must be set to the ip address where Watson Studio Local is located

    For example, if your web browser shows this path when you are logged in to Watson Studio Local:


    Then, the url parameter must be set to https://111.22.333.444

Watson Studio Local example

wml_credentials = {
    "instance_id" : "icp",
    "url"         : "https://111.22.333.444",
    "username"    : "MNOPQRS",
    "password"    : "TUVWXYZ"
client = WatsonMachineLearningAPIClient( wml_credentials )



See: Watson Machine Learning REST API external link

To use the Watson Machine Learning REST API, you need to obtain an IBM Cloud Identity and Access Management (IAM) token. In this example, you would just supply your API key in place of the example key.

cURL example

curl -k -X POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Accept: application/json" \
--data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
--data-urlencode "apikey=123456789" \

Python example

import requests

# Paste your Watson Machine Learning service apikey here
# Use the rest of the code sample as written
apikey = "123456789"

# Get an IAM token from IBM Cloud
url     = "https://iam.bluemix.net/oidc/token"
headers = { "Content-Type" : "application/x-www-form-urlencoded" }
data    = "apikey=" + apikey + "&grant_type=urn:ibm:params:oauth:grant-type:apikey"
IBM_cloud_IAM_uid = "bx"
IBM_cloud_IAM_pwd = "bx"
response  = requests.post( url, headers=headers, data=data, auth=( IBM_cloud_IAM_uid, IBM_cloud_IAM_pwd ) )
iam_token = response.json()["access_token"]

Node.js example

var btoa    = require( "btoa" );
var request = require( 'request' );

// Paste your Watson Machine Learning service apikey here
var apikey = "123456789";

// Use this code as written to get an access token from IBM Cloud REST API
var IBM_Cloud_IAM_uid = "bx";
var IBM_Cloud_IAM_pwd = "bx";

var options = { url     : "https://iam.bluemix.net/oidc/token",
                headers : { "Content-Type"  : "application/x-www-form-urlencoded",
                            "Authorization" : "Basic " + btoa( IBM_Cloud_IAM_uid + ":" + IBM_Cloud_IAM_pwd ) },
                body    : "apikey=" + apikey + "&grant_type=urn:ibm:params:oauth:grant-type:apikey" };

request.post( options, function( error, response, body )
    var iam_token = JSON.parse( body )["access_token"];
} );


Command line client (CLI)

See: Watson Machine Learning CLI external link

Prerequisite: Install the CLI

CLI versions 3.0.1 and later

Logging in to IBM cloud with the ibmcloud login command authenticates you with the Watson Machine Learning CLI.

Note that the ibmcloud/bx plug-in SDK version must be a version 0.2.1 or greater. To confirm, run this command after login:

cat ~/.bluemix/config.json | grep "SDK"

After logging in, find and set your Watson Machine Learning instance.

ibmcloud ml list instances

This lists all Machine Learning instances available in the region and account that you selected. Note the instance ID and set it with this command:

ibmcloud ml set instance <instance-id>

CLI versions before 3.0.1

To authenticate a CLI client before version 3.0.1 on your local computer, set these environment variables on your computer:

Table 1. Environment variables
Environment variableService credentials element

Example: Setting variables for the current session on the Windows command line

set ML_ENV=https://HIJKL

Example: Setting variables for the current session on Linux or macOS

export ML_ENV=https://HIJKL

Migrating your Watson Machine Learning service instance to support IAM authentication

Support for JSON web authentication is being discontinued. If you were using the JSON web authentication token for authentication, you must migrate your Watson Machine Learning services instances out of the IBM Cloud Foundry org to a resource group in IBM Cloud so that you use the IAM authentication method.

Migrate your Watson Machine Learning service instance from a Cloud Foundry org and space to a resource group

You can migrate your Watson Machine Learning service instance from a Cloud Foundry org and space to a resource group in IBM Cloud. Resource groups include finer-grained access control by using IBM Cloud Identity and Access Management (IAM), the ability to connect service instances to apps and service across different regions, and an easy way to view usage per group.

For instructions, see IBM Cloud: Migrating Cloud Foundry service instances to a resource group.