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). From there, you will be able to: find your application credentials, fetch or update your metadata endpoint, and launch sandboxes of your app in one of your maestrano organizations.
| Table of Contents |
|---|
...
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.
...
Table of Contents absoluteUrl true style none
...
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.
...
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).
| Warning |
|---|
The |
...
fields listed below are listed in Snake case. As our SDKs respect languages conventions, fields' names may vary from an SDK to another (e.g.: Java SDK). Please, refer to your SDK documentation for the exact names to use. |
| 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: | ||
| app.host | string | Yes | Yes | -Yes (with the env. only) | - | Your application host | ||
| api.id | string | Yes | Yes | Yes | - | The id of your app | ||
| api.host | string | Yes | Yes | Yes | if "environment" is set: value for Maestrano tenant | The platform host | ||
| sso.idm | string | - | - | - | same as config.app.host | Your Identity Domain Manager | ||
| sso.init_path - | string | Yes | Yes | This value can be changed | - | Your application path that allows users to initiate Upon reaching this endpoint your application will automatically | ||
| sso.consume_path | string | - | Yes | This value can be changed on a per-tenant basis | - | Your application path to the SAML endpoint that allows | ||
| sso.idp | string | Yes | Yes | Yes | only if "environment" is set: value for Maestrano tenant | The platform host | ||
| sso.x509_fingerprint | string | - | Yes | Yes | only if "environment" is set: corresponding
| We will provide you the correct value for other tenants than Maestrano tenant | ||
| sso.x509_certificate | string | - | Yes | Yes | only if "environment" is set: corresponding
| We will provide you the correct value for other tenants than Maestrano tenant | ||
| connec.host | string | Yes | Yes | Yes | only if "environment" is set: value for Maestrano tenant | The Connec! endpoint used to fetch data from | ||
| webhook.account.groupgroups_path | string | Yes | Yes | This value can be changed on a per-tenant basis | - | Your application path where a notification will be posted | ||
| 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 | ||
| webhook.connec.notifications_path | string | Yes | Yes | This value can be changed on a per-tenant basis | - | Your application path where notifications | ||
| wenhookwebhook.connec.subscriptions | hash | Yes | Yes | No | false for all entities | The list of entities (organizations, people, invoices etc.) |
4 - How
...
can I test my integration?
The sandbox 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 tiletitle.
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.