Retrieving an access token

Get started with the IBM® Key Protect APIs by authenticating your requests to the service with an IBM Cloud® Identity and Access Management (IAM) access token.

Retrieving an access token with the CLI

You can use the IBM Cloud CLI to quickly generate your personal Cloud IAM access tokenA value used by the consumer to gain access to the protected resources on behalf of the user, instead of using the user's service provider credentials..

Log in to IBM Cloud with the IBM Cloud CLI.
```
ibmcloud login
```
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.
Select the account, region, and resource group that contain your provisioned instance of Key Protect.
Run the following command to retrieve your Cloud IAM access token.
```
ibmcloud iam oauth-tokens
```
The following truncated example shows a retrieved IAM token.
```
IAM token: Bearer eyJraWQiOiIyM...
```

Retrieving an access token with the API

You can also retrieve your access token programmatically by first creating a service ID API key for your application, and then exchanging your API key for an IBM Cloud IAM token.

Log in to IBM Cloud with the IBM Cloud CLI.
```
ibmcloud login
```
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.
Select the account, region, and resource group that contain your provisioned instance of Key Protect.

Create a service ID for your application.

ibmcloud iam service-id-create SERVICE_ID_NAME
            [-d, --description DESCRIPTION]

Managing access to resources for the service ID.

You can assign access permissions for your service ID by using the IBM Cloud console. To learn how the Manager, Writer, and Reader access roles map to specific Key Protect service actions, see Roles and permissions.
Create a service ID API key.
```
ibmcloud iam service-api-key-create API_KEY_NAME SERVICE_ID_NAME
            [-d, --description DESCRIPTION]
            [--file FILE_NAME]
```
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 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
```
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 the token.json file:
```
{
    "access_token": "b3VyIGZhdGhlc...",
    "expiration": 1512161390,
    "expires_in": 3600,
    "refresh_token": "dGhpcyBjb250a...",
    "token_type": "Bearer"
}
```
Use the full access_token value, prefixed by the Bearer token type, to programmatically manage keys for your service using the Key Protect API. To see an example Key Protect 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.
- Use IBM Cloud 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.

Example - set the access token with the 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