watsonx.ai auth failures: key, region, project ID, and IAM scope order

[watsonx troubleshooting guides]: 1) the API key is wrong, has trailing spaces, or expired. 2) the URL does not match your region. 3) the project ID is wrong or you lack access to the project. 4) missing IAM permissions. Test credentials with a minimal ModelInference call before wiring the rest of the app. On REST, a raw API key used where a Bearer token is required also returns 401: re-exchange the IAM token first. 403 means the key lacks access to that project or space, or the region URL is wrong.

Context: Most watsonx 401/403 errors trace to one of four credential fields, in this order.

Source: Most watsonx 401/403 errors trace to one of four credential fields, in this order.

Verified resolution: [watsonx troubleshooting guides]: 1) the API key is wrong, has trailing spaces, or expired. 2) the URL does not match your region. 3) the project ID is wrong or you lack access to the project. 4) missing IAM permissions. Test credentials with a minimal ModelInference call before wiring the rest of the app. On REST, a raw API key used where a Bearer token is required also returns 401: re-exchange the IAM token first. 403 means the key lacks access to that project or space, or the region URL is wrong.

Source URL: https://github.com/ibm/watsonx-developer-hub/blob/HEAD/agents/README.md