Cloud Identity

Getting Started with IBM Cloud Identity REST APIs

Share this post:

Introduction

cloud identity dashboard

Manage application access securely through IBM Cloud Identity

IBM Cloud Identity’s suite of products include robust REST APIs to be used within your applications. You can use the API framework to authenticate users, add applications, view multi-factor transactions, and a lot more. The following article is a walk-through of how to create an API client ID and secret, authenticate, and making your first API call. Should you have any questions, feel free to reach out to our support team via www.ibm.com/mysupport or comment below. There is also another good place to ask questions located here.

Getting Credentials

To make your first API call, you will need to authenticate against the authorization endpoint, however you must create API credentials via your Cloud Identity administrative portal. Follow the steps below to generate credentials for use with the API.

cloud identity api

Adding an API client for IBM Cloud Identity.

  1. Log into Cloud Identity
    Navigate to your tenant’s admin URL. This is typically in the following format: https://<yourtenant>.ice.ibmcloud.com/ui/admin and login with administrative credentials.
  2. Navigate to API Access
    This can be found under Settings > API Access
  3. Add API Client
    Click the bright blue button titled ‘Add API Client’ and give it a name, any name – it’s simply for reference.
  4. Choose Entitlements
    Select all the of the actions that you want to give rights to this API client. You can select the toggle to enable every thing or selectively choose. Save the client.
  5. Get API Client ID and Secret
    After you have saved the client, a Client ID and Client Secret will be created. You can get these values by editing the API Client again.
    The format of this will be will be:

    1. Client ID: 1593359b-poiu-tyui-xyza-abcdefgh1234
    2. Client Secret: xXXxXXxXXX

API Authentication

In order to make your first call, you will need to authenticate to the API endpoint for IBM Cloud Identity.

The URL for authorization is:

https://://tenant.ice.ibmcloud.com/v1.0/endpoint/default/token

With your API Client ID and Secret, you can make a REST call in the following format. Replace the corresponding {{clientID}} with your client ID  and the {{cilentSecret}} with your client secret from the administrator portal.

Authorization Call:

curl -X POST \
https://tenant.ice.ibmcloud.com/v1.0/endpoint/default/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id={{clientID}}&client_secret={{clientSecret}}&scope=openid'

Response:

{
"access_token": "iUPgxxGjO4AD0tzkhVdRO8FE6f08CTKny4AbUl18",
"scope": "openid",
"grant_id": "fe59154b-e1ba-45fc-97e4-60de5307d049",
"id_token": "eyJhbGciOiJub25lIn0.eyJleHQiOiJ7XCJ0ZW5hbnRJZFwiOlwiY2FzZXNlY3VyaXR5LmljZS5pYm1jbG91ZC5jb21cIn0iLCJyZWFsbU5hbWUiOiJjbG91ZElkZW50aXR5UmVhbG0iLCJhdF9oYXNoIjoibXJDRmRLeDZxU09ObC1ibXlTSkdqQSIsImlzcyI6Imh0dHBzOi8vY2FzZXNlY3VyaXR5LmljZS5pYm1jbG91ZC5jb20vb2lkYy9lbmRwb2ludC9kZWZhdWx0IiwiYXVkIjoiOWRiOTVmN2QtYjUyNS00YWQwLWE1ZjQtNmUxYTY4ZjRkMjkwIiwic3ViIjoiOWRiOTVmN2QtYjUyNS00YWQwLWE1ZjQtNmUxYTY4ZjRkMjkwIiwiaWF0IjoxNTQ1MzE3MjY2LCJleHAiOjE1NDUzMjQ0NjZ9",
"token_type": "Bearer",
"expires_in": 7200
}

The response is formatted as JSON. If successful you should see an access_token variable. The access_token value is what you will need to include in the authorization header when making subsequent calls. You’ll see more on this in the next section. Store this value for use in the next section.

Making API Calls

The API documentation for your tenant is located here:  https://tenant.ice.ibmcloud.com/developer/explorer/

We will make a simple call to list all applications in our environment. The endpoint for this call will be /v1.0/applications. In the header of your API call, include the following, remembering to replace the {{access_token}} variable with the access token received from the authorization response.

Authorization: Bearer {{access_token}}

Make the full REST call using Curl below:

curl -X GET \
https://tenant.ice.ibmcloud.com/v1.0/applications \
-H 'Authorization: Bearer iUPgxxGjO4AD0tzkhVdRO8FE6f08CTKny4AbUl18'

Get Application API Response (example):

{
"_embedded": {
"applications": [
{
"_links": {
"self": {
"href": "/appaccess/v1.0/applications/6611521215950655212"
}
},
"name": "Credential Viewer",
"templateId": "1",
"applicationState": true,
"approvalRequired": false,
"description": "The custom template to access any type of application.",
"provisioningMode": "",
"visibleOnLaunchpad": true,
"icon": "/appaccess/v1.0/icons/6611521215950655212_V1.png",
"defaultIcon": "/appaccess/v1.0/icons/default_logo160.png",
"customIcon": "/appaccess/v1.0/icons/6611521215950655212_V1.png",
"type": "Custom Application"
}]
},
"_links": {
"self": {
"href": "/appaccess/v1.0/applications"
}
},
"totalCount": #
}

Summary

Using the IBM Cloud Identity REST API, you are able to fully manage your Cloud Identity environment within your own applications. Experiment with sending 2FA transactions and validating them, manage user profiles, and even brand your portal pages! If you need any assistance,

Click here to rate this article

Rate this article :

More Cloud Identity stories
By Jeroen Tiggelman on August 4, 2019

IBM Security zSecure Suite 2.4 announced

IBM Security zSecure suite V2.4 was announced on July 23, 2019 with a planned availability date of September 30, 2019. You can read the US announcement letter here. RACF has made new JSON Web Token functionality in support of Multi-Factor Authentication also available for z/OS V2.2 and V2.3. Details about zSecure compatibility fixes can be […]

Continue reading

By Gerard Boekhoud on July 24, 2019

IF001 for IGI 5.2.5.1 now available

On July 19, 2019 we made  IF001 on top of IGI 5.2.5.1 publicly available on FixCentral. This iFix include some strong performance improvements especially within the Access Certification module. Improvements are made in the following areas: a. Time to launch Campaign Summary Page (Especially in the event of a high number of campaigns). This improves by […]

Continue reading

By Martin Schmidt on July 11, 2019

Modernizing your B2C Portal Security – LDAP Proxy Deep Dive

In this part of our series we are taking a deeper look on how the LDAP reverse proxy works and what is needed to be done to make it work. Enable CI In this part we look at what needs to be done on the CI side and what information needs to be collected. We […]

Continue reading