Docs
...
Managing task credentials
Managing task credentials
Last updated: Mar 04, 2025
Managing task credentials

Task credentials is a user-generated API key, securely stored in Vault, that facilitates authentication for requests to IBM Cloud Services. Task credentials are used to run certain tasks in a service or to enable the execution of long operations, such as scheduled jobs, without interruption.

In IBM watsonx, IBM Cloud API keys are used as task credentials. You can either provide an existing IBM Cloud API key, or you can generate a new key. Only one task credential can be stored per user, per IBM Cloud account.

Task credentials make API keys available to long-running, asynchronous workloads that are triggered by actions you take in the product user interface. You do not use task credentials when you interact with IBM watsonx programmatically.

If your service requires a task credential to perform an operation, you are prompted to provide it in the form of an API key (existing or newly generated).

Any user with an IBM Cloud account can create an API key. Service administrators are responsible for defining a strategy to revoke task credentials when these are no longer required.

Accessing task credentials

To access your task credentials follow these steps:

  1. Log in to watsonx (https://dataplatform.cloud.ibm.com/wx/) and then go to your profile tab: Open the Profile tab

  2. Choose Profile and settings: Click on Profile and settings

  3. Choose the User API key tab: Choose the User API key tab

Creating task credentials from the UI

To create new task credentials:

From the User API key tab, click Create key. You'll see your new API key appear in the key list: Generated task credentials

Creating task credentials programmatically

Scenario 1: Creating task credentials for an existing Service ID

If you use serviceIDs, you can't use UI Path to create task credentials. You must execute the following cURL request to create a task credential for the specified serviceID. This credential will be used for creating deployments, deployment jobs, and other related operations:

curl -X POST "https://<your cloud URL>/v1/task_credentials" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <your service id api key token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SERVICE_ID_TASK_CREDENTIALS",
    "description": "string",
    "type": "iam_api_key",
    "secret": {
      "api_key": "<your service id apikey>"
    }
  }'

Repeat this for all the geographical locations. For details, refer to the URLs of available geographical locations.

After creating task credentials, wait for 15 to 20 minutes before re-triggering the failed jobs or deployments (precautionary measure) so the data is synced for your newly created task credentials.

Scenario 2: Creating task credentials for regular users (by using API)

Execute the following cURL request to create a task credential:

curl -X POST "https://<your cloud URL>/v1/task_credentials?owner.user_id=<your IBM user ID>&owner.account_id=<your IBM account ID>" \
  -H "accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "USER_TASK_CREDENTIALS",
    "description": "string",
    "type": "iam_api_key",
    "secret": {
      "api_key": "<your api key>"
    }
  }'

Repeat this for every other location. For details, refer to the URLs of available geographical locations.

URLs of available geographical locations

Managing existing task credentials

To re-generate your key, from the User API key tab, click Rotate key. You'll see your new API key appear in the key list.

To delete your key, from the User API key tab, click the Delete icon. delete icon

Learn more

Parent topic: Administering projects