---
name: watson-getting-started-iam
title: Authenticating to Watson services
description: IBM Watson® services on IBM Cloud® use IBM Cloud® Identity and Access Management (IAM) for authentication. Services installed on IBM Cloud Pak® for Data support more methods. 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.
last-updated: 2023-01-14
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/watson?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Authenticating to Watson services
{: #iam}

IBM Watson® services on IBM Cloud® use IBM Cloud® Identity and Access Management (IAM) for authentication. Services installed on IBM Cloud Pak® for Data support more methods. 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.
{: shortdesc}

## Passing credentials
{: #gs-iam-credentials}

To authenticate to a service through its API, pass your credentials to the API. How you authenticate can vary depending on security needs and whether the service is on IBM Cloud® or installed on IBM Cloud Pak® for Data.

### Authenticating to IBM Cloud
{: #gs-credential-cloud}

[IBM Cloud]{: tag-ibm-cloud}

You use IBM Cloud® Identity and Access Management (IAM) to make authenticated requests to public IBM Watson® services. You can pass either a bearer token in an authorization header or an API key.

-   Authenticate with an IAM token.

    IAM tokens are temporary security credentials that are valid for up to 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](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey&format=markdown).

    The following `curl` command generates an IAM access token. Replace `{apikey}` with the value of your API key.

    ```sh
    curl -X POST \
    -header "Content-Type: application/x-www-form-urlencoded" \
    -data "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={apikey}" \
    "https://iam.cloud.ibm.com/identity/token"
    ```
    {: pre}

    The response includes an `access_token` property. To authenticate a request to the service, replace `{access_token}` with the token from the response. Replace `{url}` with the value of the URL for your service instance, which you can find by clicking **Show Credentials** in the **Credentials** box of the **Manage** page for your service instance.

    ```sh
    curl -header "Authorization: Bearer {access_token}" \
    "{url}/v1/{method}"
    ```
    {: pre}

-   Authenticate with an IBM Cloud API key, a service ID API key, or a service-specific API key. Replace `{url}` with the value of the URL for your service instance, which you can find by clicking **Show Credentials** in the **Credentials** box of the **Manage** page for your service instance.

    API keys are simple to use and don't automatically expire. Anyone with a valid key can access the resource. You can create separate API keys for different users, different applications, or to support key rotation scenarios. You can revoke API keys from the console without interfering with other API keys or the user.

    The following example `curl` command authenticates with the API key `f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI`.

    ```sh
    curl -u "apikey:f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI" \
    "{url}/v1/{method}"
    ```
    {: pre}

For testing and development, you can pass in an API key directly. However, for production use, unless you use the Watson SDKs, use an IAM token. When you pass an API key, the service looks up the API key details, so it might affect performance. For more information, see [Invoking IBM Cloud service APIs](https://cloud.ibm.com/docs/account?topic=account-iamapikeysforservices&format=markdown).

The Watson SDKs support both methods. For more information, see the **Authentication** section of the [API reference](https://cloud.ibm.com/docs?tab=api-docs&category=ai){: external} for your service and SDK.

Some service plans support IBM® Key Protect for IBM Cloud® to control access to data. For more information, see [Protecting sensitive information in your Watson service](https://cloud.ibm.com/docs/watson?topic=watson-keyservice&format=markdown).
{: note}

### Authenticating to IBM Cloud Pak for Data
{: #gs-credential-cpd}

[IBM Cloud Pak for Data]{: tag-cp4d}

You authenticate to the service by passing an access token with each request. You pass a bearer token in an `Authorization` header to authenticate. Several methods exist to generate the token, including by using an API key or by username. For more information, see [Generating an authorization token or API key](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.6.x?topic=resources-generating-authorization-token-api-key).

For more information about authentication methods that are supported by the Watson SDKs for services installed on IBM Cloud Pak for Data, see the **Authentication** section of the [API reference](https://cloud.ibm.com/docs?tab=api-docs&category=ai){: external} for your service and SDK.

## About API keys
{: #gs-iam-keys}

Three types of API keys are supported by Watson services:

- Service-specific API keys

    Service-specific keys are generated with the service. This kind of API key has access only to a specific service instance. To view service-specific keys, click the name of a Watson service from your [resource list](https://cloud.ibm.com/resources?groups=resource-instance){: external}.

- IBM Cloud API keys

    IBM Cloud API keys are associated with a user's identity. Only the user who is associated with the key can delete it. The same IBM Cloud API key can be used to access different services. For more information about working with IBM Cloud API keys, see [Managing user API keys](https://cloud.ibm.com/docs/account?topic=account-userapikey&format=markdown).

- Service ID API keys

    Service IDs enable access to your IBM Cloud services by applications hosted both inside and outside of IBM Cloud. API keys that are associated with service IDs are granted the access that is associated with that service ID. For more information about service ID keys, see [Managing service ID API keys](https://cloud.ibm.com/docs/account?topic=account-serviceidapikeys&format=markdown).

## API key best practices
{: #gs-iam-api-bp}

Keep your API keys secure to reduce the chance of publicly exposing credentials that compromise your account and applications. To help keep your API keys secure, follow these guidelines.

- Assign the most restrictive service role that works for the level of access you need.

    For example, assign the `Reader` service role for calls from your application to `GET` API methods. This role has only read-only access, so can't create or edit resources.

- Don't embed the API key directly in code.

    API keys that are embedded in code might be exposed to your users. Instead of embedding the API keys in code, store them either in environment variables or in files outside your source code control system.
- Don't store an API key in files inside your application's source code control system.

    If you store API keys in files, keep the files outside of your application's source code. This practice is important if you use a public source code management system such as GitHub.

- Regenerate or rotate your API keys.

    Create new keys periodically, or rotate your keys. And don't forget to delete keys that you no longer use.

## Next steps
{: #gs-iam-next-steps}

- Read an overview of [IBM Cloud IAM](https://cloud.ibm.com/docs/account?topic=account-iamoverview&format=markdown)
- Learn about [managing access](https://cloud.ibm.com/docs/account?topic=account-cloudaccess&format=markdown) in IBM Cloud
- Dive into [policies, user roles, and permissions](https://cloud.ibm.com/docs/account?topic=account-userroles&format=markdown)
- See how to [pass API keys and tokens](https://cloud.ibm.com/docs/account?topic=account-iamapikeysforservices&format=markdown)