Application API: Define user access

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

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

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

About this API

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

  • API Key: Acoustic Exchange 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 Acoustic Exchange reports a registration request, Acoustic Exchange 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 Acoustic Exchange to notify you when Acoustic Exchange 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 Acoustic Exchange only for events that are actually requested by Acoustic Exchange users. Subscription monitoring has the benefit of indicating which events are the most or least popular among Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange application APIs.
include Subscription Notifications Optional string true|false If true, Acoustic Exchange sends a notification that a Acoustic Exchange user has added an event subscription.
subscription NotificationUrl Required if you send notifications. URL As required Enter the URL where you want Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange user interface.
type Optional string

Integer

String

For Integer: If you specify PROMPT for the value property, Acoustic Exchange 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: Acoustic Exchange prompts the user to enter a user name.

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

password Required String

PROMPT

As required

PROMPT: Acoustic Exchange prompts the user to enter a password.

Otherwise, enter a fixed value that Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange must use to generate an OAuth access token when it sends a
subscription notification.
clientID Required String As required Provide the OAuth clientID that Acoustic Exchange must submit when it sends a subscription notification.
clientSecret Required String As required Provide the OAuth client secret that Acoustic Exchange must submit when it sends a subscription
notification.
refreshToken Required String As required Provide the OAuth refresh token that Acoustic Exchange 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 Acoustic Exchange 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: Acoustic Exchange prompts the user to enter a refresh token.

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

Response

Acoustic Exchange 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 Acoustic Exchange has stored that defines how Acoustic Exchange 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 Acoustic Exchange account.

The application ID is the value that Acoustic Exchange 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

Acoustic Exchange 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 *