Credentials for programmatic access (IBM Cloud API key and IAM token)

Last updated: Feb 03, 2025

To work with foundation models in IBM watsonx.ai programmatically, you must authenticate to prove that you are authorized to access watsonx.ai resources.

REST API credentials

For most API methods, you must include an IBM Cloud Identity and Access Management (IAM) bearer token as your access token with the request. You use an IBM Cloud API key to generate an IAM bearer token.

To authenticate REST API requests, complete the following steps:

You can create the IBM Cloud API key in various ways.

For more information, see IBM Cloud API key.
Use the IBM Cloud API key to create an IAM bearer token.

For more information, see Generating an IBM Cloud IAM token by using an API key.

Specify the IAM token when you submit a REST request.

curl -X 'POST' https://{region}.ml.cloud.ibm.com/ml/v1/text/generation
--header "Authorization: Bearer {IAM-token}..."

You are responsible for refreshing the token when it expires. To refresh the token, repeat the procedure starting from Step 2.

Python library credentials

When you use the Python library, you can choose to use an API key or an IAM token.

If you create the IAM token yourself and pass the token to the library, then you must manage refreshing the token before it expires.

When you pass your API key to the APIClient in the library, the client generates the IAM token and refreshes the token as needed.

Using the IBM Cloud API key with the library

You can create the IBM Cloud API key in various ways. For more information, see IBM Cloud API key

The following sample code snippet shows how an API key is used directly for authentication when using the Python library.

from ibm_watsonx_ai.foundation_models import ModelInference

model_inference = ModelInference(
    model_id="ibm/granite-13b-chat-v2",
    credentials={
        "apikey": "***",
        "url": "https://{region}.ml.cloud.ibm.com"
    },
    project_id="*****"
    )

Using the APIClient

Alternatively, you can use the APIClient that is available in the library. After you instantiate the client, you don't need to specify credentials with each method.

from ibm_watsonx_ai import APIClient
from ibm_watsonx_ai import Credentials

credentials = Credentials(
  url = "https://{region}.ml.cloud.ibm.com",
  api_key = "{api-key}"
)

client = APIClient(credentials)

For more information, see Authentication.

You can set a default project or space ID also. For more information, see Finding the project ID.

Creating task credentials

For some long-running jobs or tasks, such as tuning foundation models, a task credential is required.

To create a task credential:

task_credentials_details = client.task_credentials.store()

To list credentials:

client.task_credentials.list()

The list of credentials that is returned includes an asset_id, which is the task credential ID, for each task credential.

When you know the ID for the credential, you can delete it as follows:

client.task_credentials.delete(task_credentials_id)

For more information, see the Task credentials class in the Python library.

Alternatively, you can use the product UI to create or delete task credentials. For more information, see Managing task credentials.

Learn more

Parent topic: Coding generative AI solutions