Important:

IBM Cloud Pak® for Data Version 4.7 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.7 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

Authenticating for programmatic access (Watson Machine Learning)

To use Watson Machine Learning with the Python client library or the REST API, you must authenticate to secure your work. Learn about the different ways to authenticate.

How you authenticate depends on:

whether you are using a notebook within Watson Studio or whether you are accessing Watson Machine Learning from outside the cluster
whether IAM (Identity and Access Management) authentication is enabled or disabled (by default, during CPD installation the iamintegration parameter is set to False)

As an alternative, you can use the username and apikey combination to authenticate. You can retrieve your API key from UI by going to your profile page, and clicking the API key button.

Example of using a username and apikey combination:

wml_credentials = {
    "username": "<username>",
    "apikey": "<apikey>",
    "instance_id" : "openshift",
    "url": <web client url>,
    "version": "4.0"
}

Note:

For <web client url>, refer to Finding the web client url.

Authenticating from a notebook from within Watson Studio

Watson Machine Learning requires a bearer token to authenticate the user calling the REST APIs. The token expires after 12 hours. To access a token when you create a notebook in Watson Studio, use this code:

from ibm_watson_studio_lib import access_project_or_space
wslib = access_project_or_space()
token = wslib.auth.get_current_token()

Important: The alternative is using `token = os.environ['USER_ACCESS_TOKEN']`. The `USER_ACCESS_TOKEN` environment variable is deprecated and will be removed in a future release.

You can also retrieve a bearer token from the user management service by using an API call:

If IAM integration was disabled during installation (default setting), refer to Getting a bearer token with IAM integration disabled.
If IAM integration was enabled during installation, refer to Getting a bearer token with IAM integration enabled.

For information on how to use the token, refer to Using the token to authenticate with the server.

Getting a bearer token with IAM integration disabled

Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

Type this command:

curl -k -X POST <web client url>/icp4d-api/v1/authorize -H ‘cache-control: no-cache’ -H ‘content-type: application/json’ -d ‘{"username":"<username>","password":"<password>"}’

Where you specify your username and password for accessing the Cloud Pak for Data cluster.

The call returns a JSON snippet from which the bearer token can be extracted from the access_token field:

{
  "username": "admin",
  "role": "Admin",
  "permissions": [
    "administrator"
  ],
  "sub": "admin",
  "iss": "KNOXSSO",
  "aud": "DSX",
  "uid": "999",
  "authenticator": "default",
  "access_token": "<bearer token>",
  "_messageCode_": "success"
  ....
}

Copy the token to your Python program.

Getting a bearer token with IAM integration enabled

Find the IBM Cloud Pak foundational services URL. Refer to Finding the IBM Cloud Pak foundational services URL.

You will use the <foundational services url> in next steps.

Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

Obtain the temporary IAM access token:

curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
-d "grant_type=password&username=<username>&password=<password>&scope=openid" \
<foundational services url>/idprovider/v1/auth/identitytoken

Using the IAM access token, request the bearer token:

curl -k X GET '<web client url>/v1/preauth/validateAuth' \
-H 'username: admin' \
-H 'iam-token: <iam token>'

Copy the token to your Python program.

Using the token to authenticate with the server

Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

Use your bearer token to connect to the server. This will mask your user credentials:

wml_credentials = {
"token": "<token>",
"instance_id" : "openshift",
"url": "<web client url>",
"version": "4.0"
}

from ibm_watson_machine_learning import APIClient
client = APIClient(wml_credentials)

For troubleshooting, refer to the Troubleshooting section.

Authenticating the Python client from outside of Watson Studio

If you are not storing your notebook within Watson Studio, you can bypass retrieving a token and authenticate with your Cloud Pak for Data credentials.

Find your web client url. Refer to Finding the web client url.

You will use the <web client url> in next steps.

To authenticate, type the following:

wml_credentials = {
    "instance_id" : "openshift",
    "url"         : "<web client url>",
    "username"    : "<username>",
    "password"    : "<password>",
    "version"     : "4.0"
}

from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

For an example of using authentication with a notebook, refer to Machine learning Python samples and examples.

For troubleshooting, refer to the Troubleshooting section.

Troubleshooting

If you receive this message when you are creating an instance of the client:

Attempt of generating `bedrock_url` automatically failed. If iamintegration=True, please provide `bedrock_url` in wml_credentials. If iamintegration=False, please validate your credentials.

Check the contents of the wml_credentials dictionary for errors. If you don't find any errors and the issue still appears, check whether during CPD installation the iamintegration parameter was set to True

If the iamintegration parameter was set to True, try adding this line of code to the wml_credentials dictionary:

"bedrock_url": "<foundational services url>"

Refer to Finding the IBM Cloud Pak foundational services URL.

Finding the IBM Cloud Pak foundational services URL

The IBM Cloud Pak foundational services URL is the Red Hat OpenShift route that is created by IBM Common Services. By default, the IBM Cloud Pak foundational services namespace is ibm-common-services, so you can find the IBM Cloud Pak foundational services URL by typing this command:

oc get routes -n ibm-common-services

The command returns the following output:

NAME                HOST/PORT                     PATH   SERVICES                   PORT    TERMINATION            WILDCARD
<cp-console>        <foundational services url>          <service name>             https   reencrypt/Redirect     None
<cp-proxy>          <proxy URL>                          <service name>             https   passthrough/Redirect   None

Finding the web client url

To find the web client url, view the details for the service instance from the address field in the web client.

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

https://some-route.apps.your.server.company.com/<xyz>

Then, the web client url parameter must be set to
https://some-route.apps.your.server.company.com

For details, refer to Endpoint URLs

Learn more

For real-life authentication examples, refer to sample notebooks:

View a full set of Machine learning Python client sample notebooks.

Parent topic: Managing predictive deployments