Retrieving an access token

Get started with the Hyper Protect Crypto Services key management service API by authenticating your requests to the service with an IBM Cloud® Identity and Access Management (IAM) access token.

An access token is a temporary credential that expires after 1 hour. After the acquired token expires, you must generate a new token to continue calling IBM Cloud or service APIs. To maintain access to the service, regenerate the access token for your API key regularly.

Retrieving an access token with the CLI

You can use the IBM Cloud CLI to quickly generate your personal Cloud IAM access 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 region and resource group where you would like to create a Hyper Protect Crypto Services service instance. You can use the following command to set your target region and resource group.
```
ibmcloud target -r <region_name> -g <resource_group_name>
```
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 using an API key, and then exchanging your API key for an IBM Cloud IAM token. Depending on whether you create the access token for a user or an application, use your IBM Cloud user API key or a service ID API key accordingly.

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 region and resource group that contain your provisioned Hyper Protect Crypto Services instance with the following command:
```
ibmcloud target -r <region_name> -g <resource_group_name>
```
Create an API key.
- If you want to retrieve an access token for a user, create a user API key with the following command:
```
ibmcloud iam api-key-create <API_key_name>
    [-d, --description <description>]
    [--file <API_key_file_name>]
```
  Specify the API key a unique name with the <API_key_name> parameter. Make sure to save your API key for later use by either using the <API_key_file_name> parameter or copying the API key value from the command response.
- If you want to retrieve an access token for an application, create a service ID API key by completing the following steps:
  1. Create a service ID for your application with the following command:
```
ibmcloud iam service-id-create <service_ID_name>
    [-d, --description <description>]
```
    Specify the service ID a unique name with the <service_ID_name> parameter.
  2. Create a service ID API key with the following command:
```
ibmcloud iam service-api-key-create <API_key_name> <service_ID_name>
    [-d, --description <description>]
    [--file <API_key_file_name>]
```
    Specify the API key a unique name with the <API_key_name> parameter and replace <service_ID_name> with the unique alias that you assigned to your service ID in the previous step. Make sure to save your API key for later use by either using the <API_key_file_name> parameter or copying the API key value from the command response.
Assign the user or the service ID the appropriate access to your Hyper Protect Crypto Services instance based on your access policy.

To learn how the IAM access roles map to specific Hyper Protect Crypto Services service actions, see Roles and permissions.
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:ibm:params:oauth:grant-type:apikey&apikey=<API_key>" > token.json
```
In the request, replace <API_key> with the user API key or the service ID API key that you created in the previous step. The following truncated example shows the contents of the token.json file:
```
{
"access_token": "eyJraWQiOiIyM...",
"expiration": 1512161390,
"expires_in": 3600,
"refresh_token": "...",
"token_type": "Bearer"
}
```
Use the full access_token value, prefixed by the Bearer token type, to programmatically manage keys for your service using the Hyper Protect Crypto Services key management service API. To see an example Hyper Protect Crypto Services key management service API request, check out Forming your key management service API request.