Application API/ Define user access

Acoustic Exchange APIs that you call to define how Acoustic Exchange users access an Acoustic Exchange endpoint that is based on an 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 Acoustic provided for your Acoustic Exchange account.

The base URL is the URL that Acoustic 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//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
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	IntegerString	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 data	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>"
   },

authType	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 Acoustic 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, Acoustic provides you with a Supplier key after you provide Acoustic 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>", 
   "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 Acoustic Exchange	Enter the Supplier key that Acoustic provided to you during account provisioning.
refreshToken	Required	String	PROMPTAs 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 Exchange has stored that defines how 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 Acoustic provided for your Acoustic Exchange account.

The application ID is the value that 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//deployment.

The base URL is the URL that Acoustic 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.