IBM Security Verify

Introduction

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.

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=

&client_secret=

&scope=openid'

Response:

{
"access_token": "

",
"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

 \
-H 'Authorization: Bearer 

'

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!