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.

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:

Example of dynamic configuration endpoint

#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 configuration
      # Informations & credentials for your app to connect to this marketplace API. 
      # Those values are provided automatically.
      "sso": {
        # => idm
        # By default we consider that the domain managing user identification is the same as your application host (see above app.host parameter).
        # If you have a dedicated domain managing user identification and therefore responsible for the single sign-on handshake (e.g: https://idp.my-app.com) then you can specify it in the developer platform.
        "idm": "https://demo-app-uat.your-domain.com",
    
        # => init_path (required)
        # This is the path in your application that allows users to initiate the Single Sign-On handshake.
        # Upon reaching this endpoint, users on your application will automatically create a SSO request and redirect the user to Maestrano. Maestrano will then authenticate and authorize the user.
        "init_path": "/maestrano/auth/saml/init/maestrano-dev",

        # => consume_path (required)
        # This is your application path to the SAML endpoint that allows users to finalize SSO authentication.
        # During the 'consume' action, your application sets users (and associated group) up and/or log them in.
        "consume_path": "/maestrano/auth/saml/consume/maestrano-dev",

        # => idp
        # It corresponds to the platform host.
        # The endpoint will provide you the correct host for the platform you are being connected to.
        "idp": "https://api-hub.maestrano.io",

        # => x509_fingerprint and x509_certificate
        # The endpoint will provide you the correct host for the platform you are being connected to.
        "x509_fingerprint": "1A:89:28:62:78:CE:63:26:3A:20:23:9C:20:78:36:8A:B5:2E:CC:BE",
        "x509_certificate": "-----BEGIN CERTIFICATE-----\nMIIDcjCCAlqgA (...) wjlUbMnInFMUsqbw==\n-----END CERTIFICATE-----\n"
      },

      # ===> Data Sharing
      # This section describes Connec!™ configuration
      "connec": {
        # => connec.host (required)
        # It corresponds to the endpoint used to fetch data from.
        # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to.
        "host": "https://api-connec.maestrano.com",
        "base_path": "/api/v2",
        "timeout": 300
      },

      # => Data Sharing
      # This section describes Connec!™ configuration
      "webhooks": {
        # 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
        # => group_users_path
        "account": {
          "group_path": "/maestrano/account/groups/:id/maestrano-dev",
          "group_user_path": "/maestrano/account/groups/:group_id/users/:id/maestrano-dev"
        },

        # Connec Subscriptions/Webhook
        # The following section configures the Connec!™ webhooks
        "connec": {
          "external_ids": true,
          "initialization_path": null,
          # => 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
          # based on the Connec!™ entities you receive
          "notification_path": "/maestrano/connec/notifications/maestrano-dev",
          "subscriptions": null
        }
      }
    },
    {
      "nid": "demo-app-production",
      "marketplace": "some-telco",
      "environment": "demo-app",
      "app": {
        "host": "https://demo-app-uat.your-domain.com",
        "synchronization_start_path": "/maestrano/maestrano-uat/synchronizations",
        "synchronization_toggle_path": "/maestrano/maestrano-uat/synchronizations/toggle_sync",
        "synchronization_status_path": "/maestrano/maestrano-uat/synchronizations/:cld-uid"
      },
      "api": {
        "id": "app-15dh",
        "key": "6daaadfa07701c8819ca4a6ad85948cc4b84051e0e4927aa33f29dd3faee1303",
        "host": "https://api-hub-uat.maestrano.io",
        "base": "/api/v1/"
      },
      "sso": {
        "idm": "https://demo-app-uat.your-domain.com",
        "init_path": "/maestrano/auth/saml/init/maestrano-uat",
        "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 (...) 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"
        },
        "connec": {
          "external_ids": true,
          "initialization_path": null,
          "notification_path": "/maestrano/connec/notifications/maestrano-uat",
          "subscriptions": null
        }
      }
    }
  ]
}

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

Regarding App Id and Secret

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)

# 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":[  
      {  
         "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"
      }
  ]
}

> Retrieve a specific customer

# 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 the list of users with access to your application

# Request
curl -u <my-app-id>:<my-app-secret> \
  -H "Accept: application/json" \
  https://api-hub.maestrano.com/api/v1/account/users
 
# 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 a specific user

# 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 given customer

# Request
curl -u <my-app-id>:<my-app-secret> \
  -H "Accept: application/json" \
  https://api-hub.maestrano.com/api/v1/account/users?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 REQUIRED

When a business decides to stop using your service Maestrano will issue a DELETE request to the webhook.account.groups_path endpoint on your side (e.g.: /webhooks/maestrano/groups/:id - see the metadata section above). The call is authenticated via HTTP Basic authentication using your own API credentials (shared secret).

The call is equivalent to issuing to the following cURL request on your service:

curl -u <my-app-id>:<my-app-secret> \
  -X "DELETE" \ 
  -H "Accept: application/json" \
  https://my-cloud-application.com/webhooks/maestrano/groups/cld-4

Group > Users Webhook - getting notified a of user leaving a group REQUIRED

When a user is removed from a group, access should be disabled for that specific user. In such case Maestrano will issue a DELETE request to the webhook.account.group_users_path endpoint on your side (e.g.: /webhooks/maestrano/groups/:group_id/users/:id - see the metadata section above). The call is authenticated via HTTP Basic authentication using your own API credentials (shared secret).

The call is equivalent to issuing to the following cURL request on your service:

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 REQUIRED

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.

Our billing API allows you to report charges to be incurred to your Maestrano customers. Two types of bills are currently available:

Bill: one-off charge to be incurred - e.g.: one-off purchase a specific module, template, service within your application
RecurringBill: recurring charge - e.g.: weekly/monthly/annual user subscription

Bill - Adhoc charge

The command below shows how to create a $20 adhoc bill.

# Request
curl -u <my-app-id>:<my-app-secret> \ 
  -X "POST" \
  -H 'Accept: application/json' \
  -H "Content-type: application/json" \
  -d '{"group_id":"cld-4", "price_cents":2000, "description":"Product purchase"}' \
  https://api-hub.maestrano.com/api/v1/account/bills
 
# Response
{
   "success":true,
   "errors":{},
   "data":{
      "object":"account_bill",
      "id":"bill-520",
      "group_id":"cld-4",
      "created_at":"2015-06-03T05:00:33Z",
      "updated_at":"2015-06-03T05:00:33Z",
      "price_cents":2000,
      "status":"submitted",
      "currency":"AUD",
      "units":null,
      "description":"Product purchase",
      "period_started_at":null,
      "period_ended_at":null
   }
}

This command allows you to cancel a submitted bill. Only submitted bills can be cancelled - "invoiced" bills are not cancellable.

# Request
curl -u <my-app-id>:<my-app-secret> \ 
  -X "DELETE" \
  -H 'Accept: application/json' \
  https://api-hub.maestrano.com/api/v1/account/bills/bill-520
 
# Response
{
   "success":true,
   "errors":{},
   "data":{
      "object":"account_bill",
      "id":"bill-520",
      "group_id":"cld-4",
      "created_at":"2015-06-03T05:00:33Z",
      "updated_at":"2015-06-03T05:00:33Z",
      "price_cents":2000,
      "status":"cancelled",
      "currency":"AUD",
      "units":null,
      "description":"Product purchase",
      "period_started_at":null,
      "period_ended_at":null
   }
}

Below is how to retrieve all your bills as well as a single bill:

# Retrieve all your bills
curl -u <my-app-id>:<my-app-secret> \
  -H 'Accept: application/json' \
  https://api-hub.maestrano.com/api/v1/account/bills
 
# Retrieve a specific bill
curl -u <my-app-id>:<my-app-secret> \
 -H 'Accept: application/json' \
 https://api-hub.maestrano.com/api/v1/account/bills/bill-520

The table below summarises all the fields available on the Bill model:

Field	Mode	Type	Required	Default	Description
id	readonly	string	-	-	The id of the 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
created_at	readonly	Time	-	-	When the bill was created. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z)
updated_at	readonly	Time	-	-	When the bill was last updated. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z)
status	readonly	String	-	-	Status of the bill. Either 'submitted', 'invoiced' or 'cancelled'.
currency	read/write	String	-	AUD	The currency of the amount charged in ISO 4217 format (3 letter code)
units	read/write	Decimal(10,2)	-	1.0	How many units are billed for the amount charged
period_started_at	read/write	Time	-	-	If the bill relates to a specific period then specifies when the period started. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z)
period_ended_at	read/write	Time	-	-	If the bill relates to a specific period then specifies when the period ended. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice. Uses ISO 8601 format (e.g.: 2015-06-03T05:00:33Z)
third_party	read/write	Boolean	-	false	Flag for third-party bills (e.g.: charge for SMS credits). Third party bills are not subject to commissions.

RecurringBill - Recurring subscription fees

The command below shows how to create a $29.90 recurring bill for a user license.

# Request
curl -u <my-app-id>:<my-app-secret> \ 
  -X "POST" \
  -H 'Accept: application/json' \
  -H "Content-type: application/json" \
  -d '{"group_id":"cld-4", "price_cents":2990, "description":"User license", "period": "Month", "start_date": "2015-08-27T23:22:37Z" }' \
  https://api-hub.maestrano.com/api/v1/account/recurring_bills
 
# Response
{
   "success":true,
   "errors":{},
   "data":{
      "object":"account_recurring_bill",
      "id":"rbill-523",
      "group_id":"cld-4",
      "created_at":"2015-06-03T05:02:19Z",
      "updated_at":"2015-06-03T05:02:19Z",
      "price_cents":2990,
      "status":"submitted",
      "currency":"AUD",
      "description":"User license",
      "start_date":"2015-08-27T23:22:37Z",
      "period":"month",
      "frequency":1,
      "cycles":null,
      "initial_cents":0,
      "last_execution_at":null,
      "next_execution_at":"2015-08-27T23:22:37Z",
      "remaining_cycles":null
   }
}

This command allows you to cancel a recurring bill:

# Request
curl -u <my-app-id>:<my-app-secret> \ 
  -X "DELETE" \
  -H 'Accept: application/json' \
  https://api-hub.maestrano.com/api/v1/account/recurring_bills/rbill-523
 
# Response
{
   "success":true,
   "errors":{},
   "data":{
      "object":"account_recurring_bill",
      "id":"rbill-523",
      "group_id":"cld-4",
      "created_at":"2015-06-03T05:02:19Z",
      "updated_at":"2015-06-03T05:02:19Z",
      "price_cents":2990,
      "status":"cancelled",
      "currency":"AUD",
      "description":"User license",
      "start_date":"2015-08-27T23:22:37Z",
      "period":"month",
      "frequency":1,
      "cycles":null,
      "initial_cents":0,
      "last_execution_at":null,
      "next_execution_at":"2015-08-27T23:22:37Z",
      "remaining_cycles":null
   }
}

Below is how to retrieve all your recurring bills as well as a single recurring bill:

# Retrieve all your recurring bills
curl -u <my-app-id>:<my-app-secret> \
  -H 'Accept: application/json' \
  https://api-hub.maestrano.com/api/v1/account/recurring_bills
 
# Retrieve a specific recurring bill
curl -u <my-app-id>:<my-app-secret> \
 -H 'Accept: application/json' \
 https://api-hub.maestrano.com/api/v1/account/recurring_bills/rbill-523

The table below summarises all the fields available on the RecurringBill model:

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 REQUIRED

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

Browser not supported