How to link my application to maestrano.com?

When registering your application on maestrano.com, as an application provider, you will be given an access to a Maestrano App Provider Dashboard. The technical aspects of the integration can be found in your API portal (API tab in the menu). You will find here different tabs: Production, Sandbox1, Sandbox2, etc. The "Sandbox" tabs should be used during the integration phase, and to connect our production environment to all you different non-production environments. The "Production" tab should be used for the release of your application on maestrano.com, and should be connected to your production environment.

1 - Where can I find the credentials I will have to use?

In your API portal, you will find the Production application credentials (to be used once the application goes live) and the Sandbox credentials (to be used during the integration phase, and for all non-production environment). Several Sandbox environments can be set up (with different credentials for every sandbox) if you need to manage several test environments; just ask our team if your need more sandboxes.

2 - How does the metadata endpoint work?

In order to understand your application and configure webhooks properly, Maestrano expects you to create a special "metadata" endpoint exposing the configuration of your application preferences in terms of Single Sign-On, data sharing subscriptions, webhooks etc.

Why a metadata endpoint?

We believe that this kind of configuration manifest should belong to your application which is why we ask for a special endpoint on your side. The other approach would be to make you fill a long and boring form inside your App Provider dashboard on maestrano.com... but that wouldn't help you keeping your code/configuration easy to read and maintain.

Once setup, enter the URL of your metadata endpoint into your Maestrano App Provider dashboard then click on 'Update/Fetch'.

3 - What to include in my metadata endpoint?

The metadata endpoint should return a JSON document describing your configuration. Note that the call initiated by Maestrano to retrieve your metadata is authenticated via HTTP Basic authentication using your own API credentials (shared secret).

The main fields of your metadata are:

Field	Type	Required for OpenID SSO	Required for SAML SSO	Change with the tenant and the environment	Defaults fields	Description
environment	string	-	-	Yes (with the env. only)	-	The environment of the platform your are integrated to; accepted values: - "test" (for the sandbox) - "uat" - "production"
app.host	string	Yes	Yes	Yes (with the env. only)	-	Your application host For UAT and Production environments, it must be a publicly resolvable URL (you cannot use "http://localhost:3000" for instance)
api.id	string	Yes	Yes	Yes	-	The id of your app It corresponds to the App ID on your Maestrano App Provider API Dashboard We will provide you the correct value for other tenants than Maestrano
api.host	string	Yes	Yes	Yes	if "environment" is set: value for Maestrano tenant	The platform host We will provide you the correct value for other tenants than Maestrano
sso.idm	string	-	-	-	same as config.app.host	Your Identity Domain Manager
sso.init_path	string	-	Yes	This value can be changed on a per-tenant basis	-	Your application path that allows users to initiate the Single Sign-On handshake Upon reaching this endpoint users your application will automatically create a SSO request and redirect the user to Maestrano. Maestrano will then authenticate and authorize the user. We will provide you the correct value for other tenants than Maestrano
sso.consume_path	string	-	Yes	This value can be changed on a per-tenant basis	-	Your application path to the SAML endpoint that allows users to finalize SSO authentication During the 'consume' action your application sets users and group up and/or log them in.
sso.idp	string	Yes	Yes	Yes	if "environment" is set: value for Maestrano tenant	The platform host We will provide you the correct value for other tenants than Maestrano
sso.x509_fingerprint	string	-	Yes	Yes	if "environment" is set: value for Maestrano tenant	We will provide you the correct value for other tenants than Maestrano
sso.x509_certificate	string	-	Yes	Yes	if "environment" is set: value for Maestrano tenant	We will provide you the correct value for other tenants than Maestrano
connec.host	string	Yes	Yes	Yes	if "environment" is set: value for Maestrano tenant	The Connec! endpoint used to fetch data from We will provide you the correct value for other tenants than Maestrano
webhook.account.groups_path	string	Yes	Yes	This value can be changed on a per-tenant basis	-	Your application path where a notification will be posted when an instance of your application is deleted
webhook.account.group_users_path	string	Yes	Yes	This value can be changed on a per-tenant basis	-	Your application path where a notification will be posted when a user is removed from an instance of your application
webhook.connec.notifications_path	string	Yes	Yes	This value can be changed on a per-tenant basis	-	Your application path where notifications (created/updated entities) will be POSTed to
wenhook.connec.subscriptions	hash keys: predefined entities values: boolean	Yes	Yes	No	false for all entities	The list of entities (organizations, people, invoices etc.) for which you want to be notified upon creation/update in Connec!™

4 - How can I test my integration?

One of the sandboxes application should be used during the integration phase, or for any non-production environment. You can add the application to your dashboard easily by clicking on the Start Sandbox App button and then choosing the appropriate company.
Once added to your dashboard, you can initiate the SSO process by starting the application, clicking on the application title.

To test the data sharing end-to-end between your application and another application from the Maestrano platform, you will have to launch an other application on your dashboard. When records are created/updated in a system, notifications will be sent to the other applications from your Maestrano eco-system.