copyright | lastupdated | keywords | subcollection | ||
---|---|---|---|---|---|
|
2020-03-20 |
access, IAM, token |
key-protect |
{:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:external: target="_blank" .external} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:term: .term}
{: #retrieve-access-token}
Get started with the {{site.data.keyword.keymanagementservicelong}} APIs by authenticating your requests to the service with an {{site.data.keyword.iamlong}} (IAM) access token. {: shortdesc}
{: #retrieve-token-cli}
You can use the {{site.data.keyword.cloud_notm}} CLI{: external} to quickly generate your personal Cloud IAM access token{: term}.
-
Log in to {{site.data.keyword.cloud_notm}} with the {{site.data.keyword.cloud_notm}} CLI{: external}.
ibmcloud login
{: pre}
If the login fails, run the
ibmcloud login --sso
command to try again. The--sso
parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time pass code. {: note} -
Select the account, region, and resource group that contain your provisioned instance of {{site.data.keyword.keymanagementserviceshort}}.
-
Run the following command to retrieve your Cloud IAM access token.
ibmcloud iam oauth-tokens
{: pre}
The following truncated example shows a retrieved IAM token.
IAM token: Bearer eyJraWQiOiIyM...
{: screen}
{: #retrieve-token-api}
You can also retrieve your access token programmatically by first creating a service ID API key{: external} for your application, and then exchanging your API key for an {{site.data.keyword.cloud_notm}} IAM token.
-
Log in to {{site.data.keyword.cloud_notm}} with the {{site.data.keyword.cloud_notm}} CLI{: external}.
ibmcloud login
{: pre}
If the login fails, run the
ibmcloud login --sso
command to try again. The--sso
parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time passcode. {: note} -
Select the account, region, and resource group that contain your provisioned instance of {{site.data.keyword.keymanagementserviceshort}}.
-
Create a service ID{: external} for your application.
ibmcloud iam service-id-create SERVICE_ID_NAME [-d, --description DESCRIPTION]
{: pre}
-
Managing access to resources{: external} for the service ID.
You can assign access permissions for your service ID by using the {{site.data.keyword.cloud_notm}} console{: external}. To learn how the Manager, Writer, and Reader access roles map to specific {{site.data.keyword.keymanagementserviceshort}} service actions, see Roles and permissions. {: tip}
-
Create a service ID API key{: external}.
ibmcloud iam service-api-key-create API_KEY_NAME SERVICE_ID_NAME [-d, --description DESCRIPTION] [--file FILE_NAME]
{: pre}
Replace
<service_ID_name>
with the unique alias that you assigned to your service ID in the previous step. Save your API key by downloading it to a secure location. -
Call the IAM Identity Services API{: external} to retrieve your access token.
$ curl -X POST \ "https://iam.cloud.ibm.com/identity/token" \ -H "content-type: application/x-www-form-urlencoded" \ -H "accept: application/json" \ -d 'grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>' > token.json
{: codeblock}
In the request, replace
<API_KEY>
with the API key that you created in the previous step. The following truncated example shows the contents of thetoken.json
file:{ "access_token": "b3VyIGZhdGhlc...", "expiration": 1512161390, "expires_in": 3600, "refresh_token": "dGhpcyBjb250a...", "token_type": "Bearer" }
{: screen}
Use the full
access_token
value, prefixed by the Bearer token type, to programmatically manage keys for your service using the {{site.data.keyword.keymanagementserviceshort}} API. To see an example {{site.data.keyword.keymanagementserviceshort}} API request, check out Forming your API request.Access tokens are valid for 1 hour, but you can regenerate them as needed. To maintain access to the service, regenerate the access token for your API key on a regular basis by calling the IAM Identity Services API{: external}. {: note }
-
Use {{site.data.keyword.cloud_notm}} Identity and Access Management (IAM) tokens to make authenticated requests to IBM Watson services without embedding service credentials in every call.
-
IAM authentication uses access tokens for authentication, which you acquire by sending a request with an API key.
-
{: #retrieve-token-example-cli}
This example shows how to retrieve an access token and set an environment variable using the command line interface (CLI).
# login and select account, region, and resource group
$ ibmcloud login --sso
# optionally set the region (-r) and resource group (-g) that
# contains your provisioned Key Protect instance
$ ibmcloud target -r us-south -g Default
# set the ACCESS_TOKEN environment variable (with Bearer)
$ export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
# show the access token
$ echo $ACCESS_TOKEN
Bearer eyJraWQiOiIyMDIwMDcyNDE4MzEiLCJh ...<redacted>... o4qlcKjl9sVqLa8Q
# set the ACCESS_TOKEN environment variable (without Bearer)
$ export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d ' ' -f 5 | sed 's/^ *//'`
$ echo $ACCESS_TOKEN
eyJraWQiOiIyMDIwMDcyNDE4MzEiLCJh ...<redacted>... o4qlcKjl9sVqLa8Q
{: screen}