Application API: Define user access

UBX APIs that you call to define how UBX users access a UBX endpoint that is based on a UBX application.

PUT /v1/application/{applicationid}/deployment/{deploymentid}/onboarding

Specify or update the connection information that is defined for a deployed UBX application.

About this API

After UBX users start the endpoint registration process by generating an endpoint-level authentication key in the UBX user interface, they must be able to authenticate with your endpoint. Call this API to specify how UBX users can add your endpoint to their UBX working environment and the access credentials they require. The API supports the following authentication methods:

  • API Key: UBX users must specify a key value when they register the endpoint.
  • HTTP Basic: Users must specify a user ID and password when they proceed to complete the registration.
  • OAuth: Users must specify a client ID and client secret when they register the endpoint.
  • OAuth with a refresh token only: Users specify a client ID and client secret during account provisioning, separately from registration for subscription notification. When UBX reports a registration request, UBX includes a refresh token, but not the client ID or client secret, in the OAuth authorization parameters in the HTTP header.

This API also contains properties to enable UBX to notify you when UBX users syndicate events on your endpoint. Monitoring event subscription changes can help you to manage system resources because you need to send event notifications to UBX only for events that are actually requested by UBX users. Subscription monitoring has the benefit of indicating which events are the most or least popular among UBX users. Additionally you will be notified when an endpoint is deleted

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The base URL is the URL that IBM assigned to your account during the initial account provisioning
process.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The deploymentID is the value that you defined when you generated the feature by calling POST v1/application/<applicationID>/deployment.

The following example illustrates a request (using curl) to specify connection using Basic authentication and prompting the user for a user name and password:

curl -v 
-X PUT 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{"onboardingType":"<connection action>","instructions":
"<instructions to user>","connectUrl":"<URL for credentials>",
"includeSubscriptionNotifications":<true|false>,
"subscriptionNotificationUrl":"<URL for notification>",
"notificationType":"<PUBLISHER_V1_1|PUBLISHER_V1_2|PUBLISHER_V1_3>",
"authentication":{"authType":"Basic","userID":"<PROMPT>","password":"<PROMPT>"},
"extraFields":[{"name":"<field name>",
"value":"<field value>","displayName" :"<name>""type":"<data type>"}]}
https://<base URL>/v1/application/{applicationid}/deployment/
{deploymentid}/onboarding

The following example illustrates the format of a complete JSON for connecting with
OAuth authentication.

Request JSON (specifying OAuth authentication)
{
   "onboardingType":"<connection action>",                    
   "instructions":"<instructions to user>",                  
   "connectUrl":"<URL for credentials>",                      
   "includeSubscriptionNotifications":<true|false>,  
   "subscriptionNotificationUrl":"<URL for notification> ",
      "notificationType":"<PUBLISHER_V1_1|PUBLISHER_V1_2|PUBLISHER_V1_3>"             
   "authentication":{
      "authType":"OAuth", 
      "authURL":"<URL for OAuth token>", 
      "clientID":"<OAuth client ID>", 
      "clientSecret":"<OAuth client secret>", 
      "refreshToken":"<refresh token>"
      },
   "extraFields":[                
      {
      "name":"<field name>",       
      "value":"<field value>",     
	"displayName":"<name>"       		                             
      "type":"<data type>"         		                             
      }
   ]
}
Property Use Data type Valid value Description
onboardingType Required string

INSTRUCTIONSONLY No authentication properties required.

DIRECTCONNECT Must define authentication properties.

INSTRUCTIONSONLY: Enter this value if you want only to display nstructions to the user in the UBX user interface to contact you directly to complete the onboarding process.

DIRECTCONNECT: Enter this if you want to specify how to authenticate with your endpoint. Optionally, you can also provide instructions to the user.

instructions Optional string As required by the authentication method and your requirements. Enter brief instructions to tell users how to authenticate with your endpoint.
connectUrl

Required only for DIRECTCONNECT.

URL URL on your site that accepts authentication requests. The URL that you specify must connect to provisioning systems where you have implemented UBX application APIs.
include Subscription Notifications Optional string true|false If true, UBX sends a notification that a UBX user has added an event subscription.
subscription NotificationUrl Required if you send notifications. URL As required Enter the URL where you want UBX to send the subscription notifications.
notificationType Optional string

PUBLISHER_V1_1

PUBLISHER_V1_2

PUBLISHER_V1_3

PUBLISHER_V1_1 is the default option. No additional attributes are sent
with the notification.

PUBLISHER_V1_2 sends the attributes publisherName
and providerName if the endpoint is set as the notification destination. If the endpoint is set as the notification publisher, the attributes destinationName and providerName are sent in the notification.

PUBLISHER_V1_3 sends a notification whenever an endpoint is disabled or deleted. In addition, it sends the same notification data that PUBLISHER_V1_2 sends.

authentication See examples.
extraFields Extra field properties provide a way for UBX users to send additional information to your site.
name Optional string User defined Name of the field that enables users to pass additional information to your endpoint.
value Optional string User defined Enter additional information. Specify PROMPT (uppercase with no leading or trailing spaces) to prompt the UBX user to enter information.
displayName Optional string User defined If you enter PROMPT for the value property, enter the prompt text here. The value that you enter displays in the UBX user interface.
type Optional string

Integer

String

For Integer: If you specify PROMPT for the value property, UBX validates that the user-entered data is and integer.

The authentication properties in the JSON vary depending on the type of authentication that you specify. Examples for other authentication properties appear below.

Basic

For registering endpoints that require basic HTTP authentication, enter the authentication properties as shown in this example. To prompt the user to enter a value, specify PROMPT as uppercase, with no leading or trailing spaces.

Authentication properties – Basic authentication
"authentication":{
   "authType":"Basic",
   "userID":"PROMPT",
   "password":"PROMPT"
   },
Property Use Data type Valid value Description
authType Required String Basic To specify basic HTTP authentication, specify Basic.
userID Required String

PROMPT

As required

PROMPT: UBX prompts the user to enter a user name.

Otherwise, enter a fixed value that UBX must pass to your endpoint.

password Required String

PROMPT

As required

PROMPT: UBX prompts the user to enter a password.

Otherwise, enter a fixed value that UBX must pass to your endpoint.

API key

For registering endpoints that require an API key to authenticate, enter the authentication properties as shown in this example. Provide the API key that UBX must submit in the header of the HTTP call that indicates a registration request.

Authentication properties – API key
"authentication":{                                 
   "authType" : "APIKey",
   "apikey" : "<API key value>"     
   },
Property Use Data type Valid value Description
authType Required String APIKey To specify authentication with an API key, specify APIKey.
apikey Required String As required by your business systems. Provide the key that UBX must submit when it sends a registration notification.

OAuth

For registering endpoints that require basic OAuth authentication, enter the authentication properties as shown in this example.

Authentication properties – OAuth
"authentication":{
   "authType" : "OAuth", 
   "authURL" : "<URL for OAuth token>", 
   "clientID" : "<OAuth client ID>", 
   "clientSecret" : "<OAuth client secret>", 
   "refreshToken" : "<refresh token>"
   },
Property Use Data type Valid value Description
authType Required String OAuth To specify OAuth authentication, specify OAuth.
authURL Required URL As required Provide the user URL that UBX must use to generate an OAuth access token when it sends a
subscription notification.
clientID Required String As required Provide the OAuth clientID that UBX must submit when it sends a subscription notification.
clientSecret Required String As required Provide the OAuth client secret that UBX must submit when it sends a subscription
notification.
refreshToken Required String As required Provide the OAuth refresh token that UBX must submit when it sends a subscription notification.

OAuth with a refresh token only

For registering endpoints that require basic OAuth authentication, enter the authentication properties as shown in this example. This example assumes that you were able to provide the OAuth clientID and clientSecret to IBM separately during the
account provisioning process. As a result, you need only to pass the refresh token in the API call.

During the provisioning process, IBM provides you with a Supplier key after you provide IBM with a clientID and clientID. You must include the Supplier key in the API call.

Authentication properties – OAuth with a refresh token only
"authentication":{
   "authType" : "OAuthRefreshTokenOnly", 
   "authURL": "<URL for OAuth token>", 
   "supplierKey" : "<supplier key from IBM>", 
   "refreshToken" : "<refresh token>"             
   },
Property Use Data type Valid value Description
authType Required String OAuthRefresh TokenOnly To specify OAuth authentication that does not require sending ClientID
and clientSecret, specify
OAuthRefreshTokenOnly.
authURL Required URL As required Provide the user URL that UBX must use to generate an OAuth access token when it sends a
subscription notification.
supplierKey Required String As provided by IBM Enter the Supplier key that IBM provided to you during account provisioning.
refreshToken Required String

PROMPT

As required

PROMPT: UBX prompts the user to enter a refresh token.

Otherwise, enter a fixed value that UBX must pass to your endpoint.

Response

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response includes a JSON payload that matches the payload of the request.

DELETE /v1/application/{applicationid}/deployment/{deploymentid}/onboarding

Remove information that defines how to connect to a deployed application.

About this API

Call this API to delete the information that UBX has stored that defines how UBX connects to your endpoint. The removal applies only to the deployment that you specify as a URL parameter in the call.

For example, you might remove the existing information so that you can define a different connection scheme.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The deploymentID is the deployment that you defined when you generated the feature by calling POST v1/application/<applicationID>/deployment.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to remove the specified connection information:

curl -v 
-X DELETE 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/{applicationid}/deployment/
{deploymentid}/onboarding

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful call removes the connection instructions from the deployment that you specified as a URL parameter in the call request.

Join The Discussion

Your email address will not be published. Required fields are marked *