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 - Single Sign-On REQUIRED
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.
2 - 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
2.1 - Membership Management
Dev Sandbox endpoint: http://api-sandbox.maestrano.io/api/v1/account/
Production endpoint: https://maestrano.com/api/v1/account/
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://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://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://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://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"
}
}
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
2.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://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://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://maestrano.com/api/v1/account/bills # Retrieve a specific bill curl -u <my-app-id>:<my-app-secret> \ -H 'Accept: application/json' \ https://maestrano.com/api/v1/account/bills/bill-520
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://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://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://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://maestrano.com/api/v1/account/recurring_bills/rbill-523