Watson Machine Learning authentication

To be able to use interfaces such as the Python client, the REST API, or the command line interface (CLI), you need to authenticate. This topic describes authentication methods for different products and interfaces.

You use IBM Cloud® Identity and Access Management (IAM) to make authenticated requests to public IBM Watson™ services. With IAM access policies, you can assign access to more than one resource from a single key. In addition, a user, service ID, and service instance can hold multiple API keys.

Authentication changes

Starting on September 1, 2020, authentication is simplified. Obtaining bearer tokens from IAM is now performed using a generic user apikey instead of a Watson Machine Learning specific apikey. It is no longer necessary to create specific credentials on the Watson Machine Learning instance.

Attention: During the migration period, you can use existing Watson Machine Learning service credentials to access your legacy V1 service instance and assets. Lite users cannot generate new credentials for a V1 service instance. Standard and Professional plan users can follow the steps in Generating legacy Watson Machine Learning credentials to generate new credentials. For details on authenticating with a legacy service instance, see the Deprecated service instance section of this topic.

Security overview

Refer to the section that describes your security needs.

Authentication credentials

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

  • 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.
  • An IAM token is an authentication token required to access IBM Cloud services. You can generate a token using your API key in the token request. For details on using IAM tokens see Authenticating to Watson Machine Learning API.

To authenticate to a service through its API, pass your credentials to the API. You can pass either a bearer token in an authorization header or an API key.

Generating an API key

To generate an API key from your IBM Cloud user account, go to Manage access and users - API Keys and create or select an API key for your user account.

Authenticate with an IAM token.

IAM tokens are temporary security credentials that are valid for 60 minutes. When a token expires, you generate a new one. Tokens can be useful for temporary access to resources. For more information, see Generating an IBM Cloud IAM token by using an API key.

Interfaces

 

Python client

See: Watson Machine Learning Python client external link Your Python client must be Python 3.6.

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

wml_credentials = {
                      "apikey":"123456789",
                      "url": " https://HIJKL"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

Note: Even though you do not explicitly provide an instance_id, it will be picked up from the associated space or project for billing purposes. For details on plans and billing for Watson Machine Learning services, see Watson Machine Learning plans and runtime usage.

Accessing a deprecated service instance

How you interact with assets developed using a v1 machine learning service instance depends on the type of plan you use.

Accessing the Python client for a “v1” service instance for a Lite user

Note: If you are a Lite plan user, your v1 machine learning service instance was automatically migrated to a v2 service instance and unmigrated assets will be read only. Use these credentials to access v1 assets. Note: to access assets developed with the v1 service instance, you must use the V3 or v4-beta APIs.

wml_credentials = {
                      "apikey":"123456789",
                      "url": " https://HIJKL",
"instance_id": "v1 lite instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

Accessing the Python client for a “v1” service instance for a standard/professional user

For standard and professional plan users, during the migration period, you can still access assets trained and deployed using the deprecated v1 service instance and you can create new assets. Use these credentials to access or create v1 assets. Note: to access assets developed with the v1 service instance, you must use the V3 or v4-beta APIs.

wml_credentials = {
                      "apikey":"123456789",
                      "url": " https://HIJKL",
"instance_id": "v1 standard instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

REST API

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" \
"https://iam.cloud.ibm.com/identity/token"

The obtained IAM token needs to be prepended with the word Bearer, and it needs to be passed in the Authorization header for API calls.

See this sample notebook for an example of how to use the token and then score a model using the REST API.

Python example

import requests

# Paste your Watson Machine Learning service apikey here

apikey = "123456789"

# Get an IAM token from IBM Cloud
url     = "https://iam.cloud.ibm.com/identity/token"
headers = { "Content-Type" : "application/x-www-form-urlencoded" }
data    = "apikey=" + apikey + "&grant_type=urn:ibm:params:oauth:grant-type:apikey"
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.cloud.ibm.com/identity/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
ML_ENVurl
ML_USERNAMEusername
ML_PASSWORDpassword
ML_INSTANCEinstance_id


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

set ML_INSTANCE=ABCDEFG
set ML_ENV=https://HIJKL
set ML_USERNAME=MNOPQRS
set ML_PASSWORD=TUVWXYZ

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

export ML_INSTANCE=ABCDEFG
export ML_ENV=https://HIJKL
export ML_USERNAME=MNOPQRS
export ML_PASSWORD=TUVWXYZ