Oracle Cloud Infrastructure Documentation

Using Access Token Authorization with My Services API

This topic explains how to set up and use access token authorization with the Oracle Cloud My Services API. Access token authorization allows a developer to access programmatic endpoints (APIs) to obtain some information (for example, entitlements, instances, or metering data) for your cloud account.

About Access Tokens

An access token contains the information required to allow a developer to access information on your cloud account. A developer presents the token when making API calls. The allowed actions and endpoints depend on the scopes (permissions) that you select when you generate the token. An access token is valid for about an hour.

A refresh token allows the developer to generate a new access token without having to contact an administrator. A refresh token is valid for about one year.

Process Overview

Setup steps for the Administrator:

  1. Create an Identity Cloud Service client application with the specific privileges you want to grant to developers.
  2. Generate an access token that contains the required privileges for the intended developer.
  3. Provide the access token and required information to the developer.
  4. Configure Identity Cloud Service for access token validation.

Steps for developer to use the token:

  1. Issue requests against My Services API endpoints. Include the access token for the authorization parameter.
  2. When the access token expires, refresh the access token without administrator intervention until the privilege is terminated.

Administrator Tasks to Set Up Token Validation

Perform the following tasks to enable developer access with an access token:

Create the IDCS client application
Generate an access token
Send the access information to a developer
Configure Identity Cloud Service for access token validation

Using the Access Token

The token file has a .tok extension. The file contains the access token and the refresh token. The content looks like:

{"app_access_token":"eyJ4N...aabb...CpNwA","refresh_token":"AQID...9NCA="}

To use the token with the My Services API:

  1. Open the token file.
  2. Issue a request to a valid endpoint, inserting the access token for the Authorization parameter.

    For example:

    curl -X GET  https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1/serviceEntitlements   -H 'Authorization: Bearer eyJ4N...aabb...CpNwA'

Requesting a New Access Token from a Refresh Token

An access token is valid for about one hour. When the token is no longer valid you will get a 401 response code and an Error Message (“errorMessage”) value containing “Expired”.

You can generate a new short-lived access token from the refresh token. You'll need the Client ID and Client Secret to generate the new token. You can only generate tokens with the same or lower access (scopes) as your original token.

Example using the curl command:

curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<tenant-IDCS-ID>/oauth2/v1/token -d 'grant_type=refresh_token&refresh_token=<refresh-token>'

Using the sample token file from the previous section, the value for <refresh-token> would be AQID...9NCA=.

Sample response:

{ "access_token": "eyJraWQiO....2nqA", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "AQIDBAUn…VkxNCB7djF9NCA=" }

Note

When a developer generates a new access token and refresh token, the previous refresh token becomes invalid.

Revoking a Developer's Ability to Refresh Access Tokens

If you need to revoke a developer's ability to refresh access tokens, you can either invalidate the existing refresh token by generating a new Client Secret for the token; or, you can temporarily revoke access by deactivating the application.

Important

Taking either of these actions will terminate or suspend the ability of all developers using the current Client Secret or application. When generating tokens for multiple developers, consider creating more than one IDCS application to isolate developers from each other.

To terminate a developer's ability to refresh their access token

  1. Sign in to Identity Cloud Services as an Administrator and go to the administration console. See How to Access Oracle Identity Cloud Service if you need help signing in.
  2. Click the Applications tile. A list of the applications is displayed.
  3. Click the application used to generate the token to view its details.
  4. Click Configuration.
  5. Under General Information, next to Client Secret, click Regenerate to generate a new Client Secret.

To restore the ability for the developer to generate an access token from a refresh token, generate a new access token. Then provide the token along with the new Client Secret to the developer.

To temporarily suspend a developer's ability to refresh their access token

  1. Sign in to Identity Cloud Services as an Administrator and go to the administration console. See How to Access Oracle Identity Cloud Service if you need help signing in.
  2. Click the Applications tile. A list of the applications is displayed.
  3. Click the application used to generate the token to view its details.
  4. In the upper right corner of the page, click Deactivate.
  5. At the prompt, click Deactivate Application.

To re-enable developers to use the same tokens, click Activate.