Maestrano currently provides four SDKs to facilitate the integration of Single Sign-On, Billing and Data Sharing. Current SDKs are: Java, PHP, Ruby and .NET.
If no SDKs are available in the language you currently use, then it may be necessary to revert to a SDK-free integration using our REST APIs directly. This guide explains how to proceed in such case.
Table of Contents | ||||
---|---|---|---|---|
|
1 How to use the developer platform dynamic configuration endpoint?
After you configured an environment on the developer platform and linked it to one or many marketplace(s), you will be able to retrieve all your marketplaces' configuration using the dynamic configuration endpoint.
The dynamic configuration endpoint return a JSON document describing your configuration for every marketplace you are linked to. To know more about how to get your app ready for multiple marketplaces, you can read this article: multi-marketplace integration.
Below is a commented example of a dynamic configuration endpoint response:
...
language | js |
---|---|
title | Example of dynamic configuration endpoint |
...
Maestrano currently provides four SDKs to facilitate the integration of Single Sign-On, Billing and Data Sharing. Current SDKs are: Java, PHP, Ruby and .NET.
If no SDKs are available in the language you currently use, then it may be necessary to revert to a SDK-free integration using our REST APIs directly. This guide explains how to proceed in such case.
...
Table of Contents | ||||
---|---|---|---|---|
|
...
1 - How to use the developer platform dynamic configuration endpoint?
After you configured an environment on the developer platform and linked it to one or many marketplace(s), you will be able to retrieve all your marketplaces' configuration using the dynamic configuration endpoint.
The dynamic configuration endpoint return a JSON document describing your configuration for every marketplace you are linked to. To know more about how to get your app ready for multiple marketplaces, you can read this article: multi-marketplace integration.
To retrieve the dynamic configuration, do a GET request to https://developer.maestrano.com/api/config/v1/marketplaces using your developer platform environment API Key and Secret.
Below is a commented example of a dynamic configuration endpoint response:
Code Block | ||||
---|---|---|---|---|
| ||||
#Request curl -u <Developer Platform API Key:<Developer Platform API Secret> -X "GET" -H 'Accept: application/json' https://developer.maestrano.com/api/config/v1/marketplaces example curl -u ddddfd-sdfsf-49b2-9675-sadfs:NRNEUmKskTyOdfdfx_1215454-X "GET" -H 'Accept: application/json' https://developer.maestrano.com/api/config/v1/marketplaces # Response { "marketplaces": [ { # => marketplace # The name of this marketplace configuration. "marketplace": "maestrano", # => nid # NID of your app on this marketplace. "nid": "demo-app-production", # => environment # The name of your application. "environment": "demo-app", # => host # This is your application informations. "app": { "host": "https://demo-app-uat.your-domain.com" }, # => Marketplace (Mno-Hub) API # Informations & credentials for your app to connect to this marketplace API. # Those values are provided automatically. "api": { "id": "608d42d2-4bf2-f76a-ba5a-f76a-XXXXXXXXXXXX", "key": "bdePCmsBXz4XXXXXXXXX", "host": "https://api-hub.maestrano.com", "base": "/api/v1/" }, # => SSO marketplaceconfiguration # The name of Informations & credentials for your app to connect to this marketplace configurationAPI. "marketplace": "maestrano", # Those values are provided automatically. # => nid "sso": { # NID of your app on# this=> marketplace.idm "nid": "demo-app-production", # => environment # The name of your application By default we consider that the domain managing user identification is the same as your application host (see above app.host parameter). "environment": "demo-app", # If you have a dedicated domain #managing =>user hostidentification and therefore responsible for the single #sign-on This is your application informations. "app": {handshake (e.g: https://idp.my-app.com) then you can specify it in the developer platform. "hostidm": "https://demo-app-uat.your-domain.com", }, # => Marketplaceinit_path (Mno-Hubrequired) API # This Informationsis &the credentialspath forin your application appthat toallows connectusers to thisinitiate marketplacethe API.Single # Those values are provided automaticallySign-On handshake. "api": { # Upon reaching this endpoint, users "id": "608d42d2-4bf2-f76a-ba5a-f76a-XXXXXXXXXXXX", "key": "bdePCmsBXz4XXXXXXXXX", "host": "https://api-hub.maestrano.com",on your application will automatically create a SSO request and redirect the user to Maestrano. Maestrano will then authenticate and authorize the user. "baseinit_path": "/maestrano/apiauth/saml/v1/" },init/maestrano-dev", # => SSO configurationconsume_path (required) # Informations &# credentialsThis foris your appapplication to connectpath to thisthe marketplaceSAML API.endpoint that allows users to finalize # Those values are provided automaticallySSO authentication. "sso": { # During the 'consume' action, your application sets #users =>(and idmassociated group) up and/or log them in. # By default we consider that the domain managing user identification is the same as your application host (see above app.host parameter). "consume_path": "/maestrano/auth/saml/consume/maestrano-dev", # => idp # IfIt youcorresponds haveto athe dedicatedplatform domainhost. managing user identification and therefore responsible for the single# sign-onThe handshake (e.g: https://idp.my-app.com) thenendpoint will provide you canthe specifycorrect ithost infor the developer platform platform you are being connected to. "idmidp": "https://demoapi-app-uat.your-domain.com", hub.maestrano.io", # => initx509_pathfingerprint (required) # This is the path in your application that allows users to initiate the Single Sign-On handshake.and x509_certificate # Upon reaching thisThe endpoint, userswill onprovide youryou applicationthe willcorrect automaticallyhost createfor athe SSOplatform requestyou andare redirectbeing theconnected userto. to Maestrano. Maestrano will then authenticate and authorize the user. "x509_fingerprint": "1A:89:28:62:78:CE:63:26:3A:20:23:9C:20:78:36:8A:B5:2E:CC:BE", "initx509_pathcertificate": "/maestrano/auth/saml/init/maestrano-dev", # => consume_path (required) -----BEGIN CERTIFICATE-----\nMIIDcjCCAlqgA (...) wjlUbMnInFMUsqbw==\n-----END CERTIFICATE-----\n" # This is your application path to the SAML endpoint that allows users to finalize SSO authentication. }, # ===> Data Sharing # During the# 'consume' action, your application sets users (and associated group) up and/or log them in.This section describes Connec!™ configuration "connec": { "consume_path": "/maestrano/auth/saml/consume/maestrano-dev", # => connec.host (required) # =>It idpcorresponds to the endpoint used to fetch data from. # It corresponds to the platform host. # It changes with the tenant and #the Theenvironment. endpointWe will provide you the correct host for the platform you are being connected to. "idphost": "https://api-hubconnec.maestrano.io", # => x509_fingerprint and x509_certificate # The endpoint will provide you the correct host for the platform you are being connected to.com", "x509base_fingerprintpath": "1A:89:28:62:78:CE:63:26:3A:20:23:9C:20:78:36:8A:B5:2E:CC:BE/api/v2", "x509_certificate": "-----BEGIN CERTIFICATE-----\nMIIDcjCCAlqgA (...) wjlUbMnInFMUsqbw==\n-----END CERTIFICATE-----\n"timeout": 300 }, # ===> Data Sharing # This section describes Connec!™ configuration "connecwebhooks": { # => connec.host (required) Maestrano will issue a DELETE request to the following paths to notify you # of any Itservice correspondscancellation to(group thedeletion) endpointor usedany touser fetchbeing dataremoved from a group. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. => groups_path # => group_users_path "account": { "hostgroup_path": "https://api-connec.maestrano.com",/maestrano/account/groups/:id/maestrano-dev", "basegroup_user_path": "/api/v2",maestrano/account/groups/:group_id/users/:id/maestrano-dev" }, # Connec Subscriptions/Webhook # The "timeout": 300 following section configures the Connec!™ webhooks }, "connec": { # => Data Sharing # This section describes Connec!™ configuration"external_ids": true, "webhooksinitialization_path": {null, # Maestrano will issue a DELETE request to the following paths to notify you # of any service cancellation (group deletion) or any user being removed from a group. # => groups_path => notifications_path (required) # This is the path of your application where notifications (created/updated entities) will be POSTed to. # You should have a controller matching this path handling the update of your internal entities # => group_users_path "account": {based on the Connec!™ entities you receive "groupnotification_path": "/maestrano/account/groups/:idconnec/notifications/maestrano-dev",dev", "subscriptions": null } "group_user_path": "/maestrano/account/groups/:group_id/users/:id/maestrano-dev" } }, { # Connec Subscriptions/Webhook"nid": "demo-app-production", "marketplace": "some-telco", "environment": "demo-app", # The following section configures the Connec!™ webhooks "app": { "connechost": { "https://demo-app-uat.your-domain.com", "externalsynchronization_start_idspath": true, "/maestrano/maestrano-uat/synchronizations", "initializationsynchronization_toggle_path": null"/maestrano/maestrano-uat/synchronizations/toggle_sync", "synchronization_status_path": # => notifications_path (required)"/maestrano/maestrano-uat/synchronizations/:cld-uid" }, "api": { # This is the path of your application where notifications (created/updated entities) will be POSTed to. "id": "app-15dh", "key": "6daaadfa07701c8819ca4a6ad85948cc4b84051e0e4927aa33f29dd3faee1303", # You should have a controller matching this path handling the update of your internal entities "host": "https://api-hub-uat.maestrano.io", "base": "/api/v1/" }, "sso": { # based on the Connec!™ entities you receive "idm": "https://demo-app-uat.your-domain.com", "notificationinit_path": "/maestrano/connecauth/saml/notificationsinit/maestrano-devuat", "subscriptions": null"consume_path": "/maestrano/auth/saml/consume/maestrano-uat", "idp": }"https://api-hub-uat.maestrano.io", } "x509_fingerprint": "861e:2e:54:c4:67:80:68:47:81:18:f7:d3:29:87:77:f8:69:54:2f", }, { "x509_certificate": "-----BEGIN CERTIFICATE-----\nMIIDezCCAuSgAwIBAgIJ "nid": "demo-app-production", "marketplace": "some-telco",(...) TnpziApEC7uUsBou2rlKmTGw==\n-----END CERTIFICATE-----\n" "environment": "demo-app"}, "appconnec": { "host": "https://demoapi-appconnec-uat.your-domainmaestrano.comio", "synchronization_startbase_path": "/maestrano/maestrano-uat/synchronizations", "synchronization_toggle_path": "/maestrano/maestrano-uat/synchronizations/toggle_syncapi/v2", "synchronization_status_pathtimeout": "/maestrano/maestrano-uat/synchronizations/:cld-uid"300 }, "apiwebhooks": { "idaccount": "app-15dh", { "keygroup_path": "6daaadfa07701c8819ca4a6ad85948cc4b84051e0e4927aa33f29dd3faee1303/maestrano/account/groups/:id/maestrano-uat", "hostgroup_user_path": "https://api-hub-uat.maestrano.io"/maestrano/account/groups/:group_id/users/:id/maestrano-uat" }, "baseconnec": "/api/v1/" { }, "ssoexternal_ids": true, { "idminitialization_path": "https://demo-app-uat.your-domain.com",null, "initnotification_path": "/maestrano/authconnec/saml/initnotifications/maestrano-uat", "consume_pathsubscriptions": "/maestrano/auth/saml/consume/maestrano-uat", null } } } "idp": "https://api-hub-uat.maestrano.io", "x509_fingerprint": "861e:2e:54:c4:67:80:68:47:81:18:f7:d3:29:87:77:f8:69:54:2f", "x509_certificate": "-----BEGIN CERTIFICATE-----\nMIIDezCCAuSgAwIBAgIJ (...) TnpziApEC7uUsBou2rlKmTGw==\n-----END CERTIFICATE-----\n" }, "connec": { "host": "https://api-connec-uat.maestrano.io", "base_path": "/api/v2", "timeout": 300 }, "webhooks": { "account": { "group_path": "/maestrano/account/groups/:id/maestrano-uat", "group_user_path": "/maestrano/account/groups/:group_id/users/:id/maestrano-uat" },] } |
...
2 - Single Sign-On
Maestrano provides two different Single Sign-On protocols: SAML 2.0 and OpenID. OpenID has become fairly more popular than SAML and is also more supported by the community. Chances are you will find a library handling OpenID out-of-the-box for your language of choice. A few examples:
- Node.js - http://passportjs.org/
- Go - https://github.com/yohcop/openid-go
- Scala/Play - https://www.playframework.com/documentation/2.0/ScalaOpenID
- Perl - http://search.cpan.org/~wrog/Net-OpenID-Consumer-1.16/lib/Net/OpenID/Consumer.pm
Our OpenID guide will give you all the details on the best way to integrate our OpenID provider into your application, just check it out here.
...
3 - Account Management API & Webhooks
Our account management API is a REST API allowing you to perform:
- Membership Management: get details about your Maestrano customers (memberships) and get notified of service cancellation actions via webhooks.
- Group/Organization
- User
- Groups Webhook
- Group Users Webhook - Mandatory
- Billing Management: create/retrieve/cancel bills or recurring bills for your Maestrano customers.
- Bill (Adhoc)
- RecurringBill
Warning | ||
---|---|---|
| ||
Beware, the my-app-id and my-app-secret used to call these API needs to be retrieved previously using a GET call to https://developer.maestrano.com/api/config/v1/marketplaces |
3.1 - Membership Management
Groups (company/organization) API
> Retrieve your list of customers (= list of companies having selected your application on Maestrano)
Code Block | ||
---|---|---|
| ||
# Request curl -u <my-app-id>:<my-app-secret> \ -H "Accept: application/json" \ https://api-hub.maestrano.com/api/v1/account/groups # Response { "success":true, "errors":{}, "data":[ { "connecobject": { "account_group", "external_idsid": true, "cld-4", "initializationcreated_path": null, at":"2014-05-21T04:04:53Z", "notificationupdated_pathat": "/maestrano/connec/notifications/maestrano-uat", "2014-05-21T04:04:53Z", "subscriptionshas_credit_card":true, null } "status":"running", } } ] } |
...
Maestrano provides two different Single Sign-On protocols: SAML 2.0 and OpenID. OpenID has become fairly more popular than SAML and is also more supported by the community. Chances are you will find a library handling OpenID out-of-the-box for your language of choice. A few examples:
- Node.js - http://passportjs.org/
- Go - https://github.com/yohcop/openid-go
- Scala/Play - https://www.playframework.com/documentation/2.0/ScalaOpenID
- Perl - http://search.cpan.org/~wrog/Net-OpenID-Consumer-1.16/lib/Net/OpenID/Consumer.pm
Our OpenID guide will give you all the details on the best way to integrate our OpenID provider into your application, just check it out here.
3 Account Management API & Webhooks
Our account management API is a REST API allowing you to perform:
- Membership Management: get details about your Maestrano customers (memberships) and get notified of service cancellation actions via webhooks.
- Group/Organization
- User
- Groups Webhook
- Group Users Webhook - Mandatory
- Billing Management: create/retrieve/cancel bills or recurring bills for your Maestrano customers.
- Bill (Adhoc)
- RecurringBill
3.1 Membership Management
Groups (company/organization) API
...
"name":"Logistics Department - Sales",
"free_trial_end_at":"2014-06-21T04:04:53Z",
"email":"cld-4@example.com",
"currency":"USD",
"timezone":"America/Los_Angeles",
"country":"US",
"city":"Los Angeles"
}
]
} |
> Retrieve a specific customer
Code Block | ||
---|---|---|
| ||
# Request curl -u <my-app-id>:<my-app-secret> \ -H "Accept: application/json" \ https://api-hub.maestrano.com/api/v1/account/groups/cld-4 # Response { "success":true, "errors":{}, "data":[ { "object":"account_group", "id":"cld-4", "created_at":"2014-05-21T04:04:53Z", "updated_at":"2014-05-21T04:04:53Z", "has_credit_card":true, "status":"running", "name":"Logistics Department - Sales", "free_trial_end_at":"2014-06-21T04:04:53Z", "email":"cld-4@example.com", "currency":"USD", "timezone":"America/Los_Angeles", "country":"US", "city":"Los Angeles" } ] } |
Users API
> Retrieve a specific customerthe list of users with access to your application
Code Block | ||
---|---|---|
| ||
# Request curl -u <my-app-id>:<my-app-secret> \ -H "Accept: application/json" \ https://api-hub.maestrano.com/api/v1/account/groups/cld-4users # Response { "success":true, "errors":{}, "data":[ { "object":"account_group", "id":"cld-4", "created_at":"2014-05-21T04:04:53Z",{ "updated_atobject":"2014-05-21T04:04:53Zaccount_user", "has_credit_cardid":true,"usr-2", "statusname":"runningJohn", "namesurname":"Doe"Logistics, Department - Sales", "free_trial_end_atemail":"2014-06-21T04:04:53Zjohn.doe@gmail.com", "emailcountry":"cld-4@example.comAU", "currencysso_session":"USDd7kp1b5esnfgtz6xhiv9qwlja34yu8crm2o0", "timezonecreated_at":"America/Los_Angeles",2014-05-21T00:37:34Z", "countryupdated_at":"US",2015-03-09T06:37:28Z" "city":"Los Angeles"} }] } |
...
> Retrieve the list of users with access to your applicationa specific user
Code Block | ||
---|---|---|
| ||
# Request curl -u <my-app-id>:<my-app-secret> \ -H "Accept: application/json" \ https://api-hub.maestrano.com/api/v1/account/users/usr-2 # Response { "success":true, "errors":{}, "data":[ { "object":"account_user", , "id":"usr-2", "name":"John", "surname":"Doe", "email":"john.doe@gmail.com", "country":"AU", "sso_session":"d7kp1b5esnfgtz6xhiv9qwlja34yu8crm2o0", "created_at":"2014-05-21T00:37:34Z", "updated_at":"2015-03-09T06:37:28Z" } ] } |
> Retrieve users of a specific usergiven customer
Code Block | ||
---|---|---|
| ||
# Request curl -u <my-app-id>:<my-app-secret> \ -H "Accept: application/json" \ https://api-hub.maestrano.com/api/v1/account/users/usr-2 ?group_id=cld-4 # Response { "success":true, "errors":{}, "data":[ { "object":"account_user", "id":"usr-2", "name":"John", "surname":"Doe", "email":"john.doe@gmail.com", "country":"AU", "sso_session":"d7kp1b5esnfgtz6xhiv9qwlja34yu8crm2o0", "created_at":"2014-05-21T00:37:34Z", "updated_at":"2015-03-09T06:37:28Z" } ] } |
Groups Webhook - getting notified a of Group cancelling their subscription to your service
Status | ||||||
---|---|---|---|---|---|---|
|
...
Code Block | ||
---|---|---|
| ||
curl -u <my-app-id>:<my-app-secret> \ -X "DELETE" \ -H "Accept: application/json" \ https://my-cloud-application.com/webhooks/maestrano/groups/cld-4/users/usr-2 |
3.2 - Billing Management
Status | ||||||
---|---|---|---|---|---|---|
|
Maestrano centralizes all billing functionalities. The goal is to provide to customers a single invoice at the end of the month summarising the expenses related to all the applications and services they have used during the month.
...
Field | Mode | Type | Required | Default | Description |
---|---|---|---|---|---|
id | readonly | string | - | - | The id of the recurring bill |
group_id | read/write | string | Yes | - | The id of the group you are charging |
price_cents | read/write | Integer | Yes | - | The amount in cents to charge to the customer |
description | read/write | String | Yes | - | A description of the product billed as it should appear on customer invoice |
period | read/write | String | - | Month | The unit of measure for the billing cycle. Must be one of the following: 'Day', 'Week', 'SemiMonth', 'Month', 'Year' |
frequency | read/write | Integer | - | 1 | The number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year. If the billing period is SemiMonth, the billing frequency must be 1. |
cycles | read/write | Integer | - | nil | The number of cycles this bill should be active for. In other words it's the number of times this recurring bill should charge the customer. |
start_date | read/write | Time | - | Now | The date when this recurring bill should start billing the customer. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z) |
created_at | readonly | Time | - | - | When the recurring bill was created. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z) |
updated_at | readonly | Time | - | - | When the recurring bill was last updated. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z) |
currency | read/write | String | - | AUD | The currency of the amount charged in ISO 4217 format (3 letter code) |
status | readonly | String | - | - | Status of the recurring bill. Either 'submitted', 'active', 'expired' or 'cancelled'. |
initial_cents | read/write | Integer | - | 0 | Initial non-recurring payment amount - in cents - due immediately upon creating the recurring bill |
...
4 - Connec!™ Data Sharing
Status | ||||||
---|---|---|---|---|---|---|
|
The Connec!™ Data Sharing REST API documentation can be found at the following URL: http://maestrano.github.io/connec/
More high level resources can also be found on this wiki, under the Connec!™ API V2 section: Connec!™ API V2 documentation