What is an endpoint?
In Acoustic Exchange, an endpoint is a representation of a business application or solution that provides or receives data through Exchange.
Products and solutions created and supported by Exchange or Exchange Business Partners can be endpoints through the partner provisioning and validation process. Appearing in Exchange as an endpoint makes it possible for marketers and business users to register the endpoint for use in their account.
Endpoint types
When you make your application or business solution available in Acoustic Exchange, you specify the type of data that the endpoint can provide and whether the endpoint is a source of data, a destination for data, or both.
Exchange users can register four types of endpoints:
- Event source
- Event destination
- Audience source
- Audience destination
When you complete partner provisioning to make your solution available as an endpoint, you indicate the type of endpoint. Exchange uses information that you provide to present the endpoint as an option in the user interface.
How it works
Users select endpoints to add to their working environment by registering endpoints with Exchange. On the Endpoints tab, Exchange provides a wizard to guide users through the registration process. As part of the Click-to-Connect endpoint registration approach, Exchange supports two methods that users can use to register endpoints and provide their authentication credentials.
- Direct connect. Users enter credentials directly through the endpoint wizard. The wizard displays entry fields based on properties that you specify in the call to the onboarding API.
- Instructions only. Users contact you to submit the credentials by following instructions that you provide to Acoustic Exchange. The registration wizard displays the exact instructions that you provide in the API call.
The endpoint registration wizard lists and describes the endpoints that are available for registration. The wizard lists your solution if you provision your endpoint by creating an Exchange application in the Integration Manager during the partner provisioning and approval process. In the Integration Manager, you describe the endpoint, indicate where it is deployed, and specify how Exchange users submit access credentials during endpoint registration.
Access the Integration Manager
You must have a Acoustic Exchange partner account to access the Integration Manager.
- Log in to Exchange, click the navigation menu and select Integration Manager in the Tools section. Integration Manager opens with the My Applications page.
- Create a new application or edit one of the applications in the list. If you create a new application, give it a unique name.
- If required, edit the application. Editing an application involves several steps.
Direct connect registration
You specify how Exchange users provide their access credentials in the Integration Manager as part of the provisioning process that enables your solution as an Exchange endpoint. To simplify the endpoint registration process, you can choose Direct connect as the method to register your endpoint.
When you use Direct connect registration, the endpoint registration wizard displays entry fields where users can enter the required endpoint access information. For example, if you require a user name and password, you can configure Direct connect to prompt users for their unique credentials. You can also define extra fields to enable users to send additional information to your systems.
Exchange submits the endpoint registration request automatically, using authentication that you specify, without the need to contact your support team.
You must provide a URL to receive the endpoint registration request and implement the systems required to accept and store the credentials that Exchange users enter. The Integration Manager indicates the required Exchange APIs.
Instructions only registration
You specify how Exchange users provide their access credentials in the Integration Manager as part of the provisioning process that enables your solution as an Exchange endpoint. The instructions that you enter in the Integration Manager display to Exchange users in the endpoint registration wizard. Typically, the instructions include guidance for a separate call to your account provisioning system. In your instructions, describe the steps that the user must take to provide their credentials, including all required links and user information.
Instructions only registration does not require you to specify an authentication method because there is no direct communication with your systems as part of the registration request.
Provisioning requirements
Specifying the provisioning method indicates to Exchange how it should provision the accounts of users who register your product or solution as an endpoint in their account. When you specify the provisioning method, you define the following provisioning requirements:
- Specify a provisioning type to indicate how Exchange users must submit endpoint registration requests.
- Specify the authentication method that Exchange must use when it communicates on behalf of the user with the operational systems that support your product or solution systems.
- Specify if you want Exchange to notify you when users subscribe to events that involve endpoints based on your application. This option applies only if you are a publisher or consumer of events.
The Integration Manager changes the provisioning options available to you based on your choice of provisioning type.
Authentication key
Exchange requires that source and destination endpoints publish and receive event and audience data through a connection made with an authentication key.
When a user registers your endpoint, Exchange generates the authentication key that is required to complete the registration process. The user must provide the key to you so you can authenticate with Exchange on behalf of the user. If you want users to contact you before they submit the access credentials and the authentication key, provide the exact instructions the users need to follow. The endpoint registration wizard displays the instructions that you provide in the API request to the Exchange onboarding API.
Each time an endpoint communicates with Exchange, the endpoint must submit the authentication key. Exchange compares the submitted authentication key to the authentication keys that it recognizes as created during endpoint registration. Each authentication key is unique to a specific account and for use by a single endpoint.
Endpoints submit the authentication key as the authorization bearer in calls to Acoustic Exchange APIs or as a URL path parameter in the API call.
Exchange always includes authentication information for direct connect endpoint registration requests. If you specify direct connect registration, you must also specify your preferred authentication method.
If you also specify direct connect endpoint registration, more authentication options are available:
- Exchange can notify you when users subscribe to events that you either produce or consume, including the authentication information in the header of the notification.
- Exchange can add authentication information for all other direct communications with your product.
Note: Integration Manager does not provide this option if you specify Instructions only registration.
Supported authentication types
Exchange supports the following authentication methods:
- API Key: You specify a key value when you register for subscription notification. When Exchange reports a subscription change in an HTTP call, it adds the specified key in the HTTP header. For example, Authorization : Bearer <API key>.
- HTTP Basic: You specify a username and password when you register for subscription notification. When Exchange reports a subscription change, it submits the credentials encoded in the HTTP header in RFC 2617 format. For example, Authorization : Basic <encoded user ID and password>.
- OAuth: You specify a client ID and client secret when you register for subscription notification. When Exchange reports a subscription change, it includes these values in the OAuth parameters that it adds to the header of the HTTP call.
- OAuth with a refresh token only: You specify a client ID and client secret during account provisioning, separately from registration for subscription notification. When Exchange reports a subscription change, it includes a refresh token, but not the client ID or client secret, in the OAuth authorization parameters in the HTTP header.
Notes on authentication
- Exchange establishes authenticated connection with endpoints through methods defined by the endpoint.
- Each endpoint must provide Exchange with the required connection and authentication information. You can specify the authentication requirements in the Exchange Integration Manager or through calls to Exchange APIs. Exchange adds the required authentication information in request headers so that it can communicate automatically with endpoint providers.
- Exchange supports securing identity and attribute data through hashing with industry standard hashing methods, to secure personal data shared by the endpoints.
Custom endpoint
If you don't use the Integration Manager to integrate with Exchange, users must register your endpoint as a custom endpoint. Registering a custom endpoint requires that the Exchange user manually generates an authentication key and submit the key to you. You must provide the means for users to submit the key and you must contact the Exchange account provisioning team to create and maintain a separate endpoint for each user account. For details and instructions, go to Register a custom endpoint.
Registering as a custom endpoint requires various API calls and extensive communication between the endpoint provider, the user, and the Exchange provisioning team, which is why we don't recommend this registration method for new integrations.
Comments
0 comments
Article is closed for comments.