IBM SaaS User and Subscription Management

Live

IBM SaaS User and Subscription Management

+ Day(s) remaining in the trial

Overview

Use these APIs to perform user management functions for your IBM SaaS subscriptions.

The IBM SaaS User and Subscription Management APIs are automatically made available to you once you register for an IBM SaaS service with API support. Use the My APIs link above if you are uncertain which APIs you are currently subscribed to.

Select your key from the left side of the screen to begin testing your APIs directly on this page. If a key is not available, one may need to be created on the My APIs page or you may need to register for an IBM SaaS service.

Getting started

Obtain Client ID and Secret

To get started you must obtain a Client ID and Secret for your organization in order to make calls. This can be done via the following steps:

  1. Login to the My APIs page of API Explorer - https://developer.ibm.com/api/mypage/
  2. Locate the IBM SaaS User and Subscription Management API
    (Note: If you don't have this you either do not have a subscription with SaaS User and Subscription Management Service or you do not have administrative roles in the customer that owns the subscription)
  3. Click the Manage your keys icon
  4. Create a new key by clicking Create or use an existing by clicking Show

Obtain an Access Token

Once you have a Client ID and Secret the first step to take in order to invoke APIs is to get an OAuth Access Token. The user authorization flow is built on top of OAuth with username and password validation. In order to generate the access token the security APIs provided by the product must be invoked. This is done by performing a POST operation with the following headers and post data to the OAuth2 endpoint - https://api.ibm.com/scx/sbs_orgaccess/oauth2/token :

  • Headers:
    • Authorization: Basic <base 64 encoded value of your client id and client secret separated by a colon>
  • Post Data:
    • grant_type=password
    • scope=/sbs_orgaccess
    • username=<Username of the admin who has rights to act on organization>
    • password=<Password of the admin who has rights to act on organization>

Here is an example with curl (uses basic auth param to generate authorization header automatically):
curl -v -u '<ClientId>:<ClientSecret>' -k -X POST -d "grant_type=password&scope=/sbs_orgaccess&username=<Username>&password=<Password>" https://api.ibm.com/scx/sbs_orgaccess/oauth2/token

In the response you will get back an access token token and a refresh token along with details of how long the access token is good for (1 hour):
{ "token_type":"bearer", "access_token":"<token value>", "expires_in":3600, "scope":"/sbs_orgaccess", "refresh_token":"<token value>" }

Refresh an Access Token

To refresh the access token after the hour expiration, another POST operation can be sent to the OAuth2 endpoint with the following headers and values:

  • Headers:
    • Authorization: Basic <base 64 encoded value of your client id and client secret separated by a colon>
  • Post Data:
    • grant_type=access_token
    • refresh_token=<refresh token retrieved earlier>

Here is an example with curl (uses basic auth param to generate authorization header automatically):
curl -v -u '<ClientId>:<ClientSecret>' -k -X POST -d "grant_type=access_token&refresh_token<refresh token>" https://api.ibm.com/scx/sbs_orgaccess/oauth2/token

In the response you will get back an access token token and a refresh token along with details of how long the access token is good for (1 hour):
{ "token_type":"bearer", "access_token":"<token value>", "expires_in":3600, "scope":"/sbs_orgaccess", "refresh_token":"<token value>" }

Making API Calls

Once you have the access token in addition to your Client ID and Secret you can start making API calls.  To do this you need to send the following headers on each API call:

  • Authorization: Bearer <access-token>
  • X-IBM-Client-Id: <client id>
  • X-IBM-Cient-Secret: <client secret>

Here is an example call to the customer API using curl:
curl -v -H 'X-IBM-Client-Id:<client id>' -H 'X-IBM-Client-Secret:<client secret>' -H 'Authorization: Bearer <access token>' -k "https://api.ibm.com/scx/sbs_orgaccess/customer?emailAddress=<admin user id>&_namedQuery=getCustomersByContactEmail&_pageNumber=1&_pageSize=10"

Pagination Parameters

All list APIs supports pagination parameters. Pagination logic uses both page number and page size parameters to filter the list returned.

  • _pageNumber - page number. Default value is 1.
  • _pageSize - page size. Maximum value permitted is 100. Default value is 25.

If the pagination parameter is not specified for the list APIs then a default values will be used.

Example:
If _pageNumber = 1 and _pageSize = 25 then list elements 1 to 25 will be included in the response.
If _pageNumber = 2 and _pageSize = 25 then list elements 26 to 50 will be included in the response.

Note that if there are no elements in the selected range an empty list would be returned. Also, if there aren't enough elements in the requested range, number of returned elements will not match the page size requested.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Documentation

IBM SaaS User and Subscription Management:

1. Customer

Get list of customers based on contact email address
This API returns a list of customers that an email address is identified as the primary contact for. The customer ID returned from this call can be used to return a list of subscriptions and subscribers (users) in subsequent API calls. See the Subscription and Subscriber sections for details on those specific topics.

GET   /customer

			https://api.ibm.com/scx/sbs_orgaccess/customer
		
Keys
Header parameters

Authorization

HEADER , required

Bearer

Path and Query parameters

emailAddress

STRING , required

Email address of the customer contact. This may be the email address used when the first subscription was established.

_namedQuery

STRING , required

Value should always be getCustomersByContactEmail

_pageNumber

STRING , optional

_pageNumber is the selector location for scanning through a list

_pageSize

STRING , optional

_pageSize enables the person to select a maximum value for the pageSize. The maximum value is 100

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/scx/sbs_orgaccess/customer?_pageSize=string&_namedQuery=string&emailAddress=string&_pageNumber=string") .header("authorization", "string") .header("accept", "application/json") .header("client_secret", "REPLACE_KEY_VALUE") .header("client_id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .asString();
Response model

201

Customer list retrieved successfully; returns list of customers

Body

400

The client submitted a request that is malformed, for example an illegal argument, a missing argument, or incomprehensible JavaScript? Object Notation (JSON)

Body

401

The client tried to invoke an operation on a resource without proper credentials.

Body

403

The client sent a request to a resource that the server is currently not making available due to an authorization error.

Body

404

The client requested an operation on a resource that does not exists.

Body

405

The client is trying to perform an operation on a resource that is not supported.

Body

500

The client submitted a request that caused a server-side exception that does not match any existing response codes.

Body

503

The client submitted a request to a server that is busy with other tasks.

Body

Response example

201

Customer list retrieved successfully; returns list of customers

								
							

400

The client submitted a request that is malformed, for example an illegal argument, a missing argument, or incomprehensible JavaScript? Object Notation (JSON)

								
							

401

The client tried to invoke an operation on a resource without proper credentials.

								
							

403

The client sent a request to a resource that the server is currently not making available due to an authorization error.

								
							

404

The client requested an operation on a resource that does not exists.

								
							

405

The client is trying to perform an operation on a resource that is not supported.

								
							

500

The client submitted a request that caused a server-side exception that does not match any existing response codes.

								
							

503

The client submitted a request to a server that is busy with other tasks.

								
							

Loading content...