Accessing your tenant using REST APIs

You need an IBM ID to access your tenant. You must also associate your IBM ID with an Identify and Access Management (IAM) access token and append the IAM access token to your API calls.

Important:

An IAM access token expires after 60 minutes.
The Platform API key is also known as an IAM or IBM Cloud API key.
Your assistant might use other IBM Cloud, Watson, or 3rd party services, each with their own API keys. You must provision and manage those keys separately.
The IFTTT integration and the Proactivity alpha features continue to use Watson Assistant Solutions API keys. To complete the tutorials, you'll find your API key by clicking on the console.

You can manually generate an IAM access token and append the token to your REST API calls. Alternatively, you can use a printToken.js script that is provided to generate a token and call this script from the header of your REST API calls.

Option 1: Generating an access token manually

1. Create an IBM ID

Go to Create your IBM account. The My IBM registration form displays.
Complete the form, create a password, and click Continue.
Review the information about email and communications. Check the boxes if appropriate.
Click Submit. A thank you message displays.

2. Create a Platform API Key

Log in to the IBM Cloud console.
Go to Manage > Security and select Platform API keys.
Click Create.
Enter a name for your API key.
Click Create.
Then, click Show to display the API key to copy and save it for later, or click Download.

3. Create an IAM access token

Convert your Platform API key to an IAM access token using the following curl command:

curl -X POST https://iam.ng.bluemix.net:443/oidc/token -H 'accept: application/json' -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=your-platform-API-key'

The response includes a JSON blob containing 'access_token', 'refresh_token', 'token_type', 'expires_in', and 'expiration'.

Important: The response includes two tokens. Make sure to copy the 'access_token' only.

4. Append your access token to your REST API calls

Append your IAM access token to your API calls. For example:

curl -X POST 'https://watson-personal-assistant-toolkit.mybluemix.net/v2/api/skillsets/industry/converse' -d '{ "text": "Hello", "language": "en-US", "userID": "application-14c", "deviceType": "phone", "additionalInformation": { "context": {} } }' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'authorization: Bearer paste-your-IAM-token-here'

If multiple tenants are configured for your deployment, specify a tenant ID in the header. For example:

curl -X POST 'https://watson-personal-assistant-toolkit.mybluemix.net/v2/api/skillsets/industry/converse' -d '{ "text": "Hello", "language": "en-US", "userID": "application-14c", "deviceType": "phone", "additionalInformation": { "context": {} } }' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'tenantID: paste-your-tenant-ID-here' -H 'authorization: Bearer paste-your-IAM-token-here'

Option 2: Generate an access token using the printToken.js script

1. Create an IBM ID

Go to Create your IBM account. The My IBM registration form displays.
Complete the form, create a password, and click Continue.
Review the information about email and communications. Check the boxes if appropriate.
Click Submit. A thank you message displays.

2. Create a Platform API Key

Log in to the IBM Cloud console.
Go to Manage > Security and select Platform API keys.
Click Create.
Enter a name for your API key.
Click Create.
Then, click Show to display the API key to copy and save it for later, or click Download.

3. Download and test the printToken.js script

Copy the printToken.js code and save it to a file named printToken.js on your file system. The script generates the access token using your Plaform API key.
Install NodeJS.
From the commmand line, enter npm install.
Add the printToken.js script to your path.
Verify that the printToken.js script generates a token. Enter:
```
node printtoken.js paste-your-Platform-API-key-here
```

4. Call the printToken.js script from your REST API calls

For example:

curl -X POST 'https://watson-personal-assistant-toolkit.mybluemix.net/v2/api/skillsets/industry/converse' -d '{ "text": "Hello", "language": "en-US", "userID": "application-14c", "deviceType": "phone", "additionalInformation": { "context": {} } }' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'authorization: Bearer "node printToken.js paste-your-Platform-API-key-here"'

Next topic

Planning checklist