...
Code Block | ||
---|---|---|
| ||
{ # ===> App Configuration # # => environment # The environment of your application. Common values are: # - "production", for your integration on a platform in a Production environment or UAT environment # - "production-sandbox", for the sandbox you use for your tests during the integration on maestrano.com # - "test", for the SSO test on the Sandbox "environment": "test", # => host (required) # This is your application host. For UAT and Production environments, it must be a publicly resolvable URL, you cannot use "http://localhost:3000" for instance. "app": { "host": "http://my-app.com" }, # "api": { # => id (required) # The id of your app. # For maestrano.com integration, it corresponds to the App ID of your Maestrano App Provider API Dashboard. # For other platform, we will send it to you with your API key. "id": "app-19op", # => host (required) # It corresponds to the platform host. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "host": "http://api-sandbox.maestrano.io" }, # ===> SSO Configuration # "sso": { # => idm # By default we consider that the domain managing user identification is the same as your application host (see above config.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 below "idm": "https://idp.myapp.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 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.php", # This value can be changed on a per-tenant basis: # "init_path": "/maestrano/auth/saml/init.php?tenant=mytenant" # => 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.php", # This value can be changed on a per-tenant basis: # "consume_path": "/maestrano/auth/saml/consume.php?tenant=mytenant" # => idp (required) # It corresponds to the platform host. # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "idp": "https://maestrano.com", # => x509_fingerprint and x509_certificate # It changes with the tenant and the environment. We will provide you the correct host for the platform you are being connected to. "x509_fingerprint": "8a:1e:2e:76:c4:67:80:68:6c:81:18:f7:d3:29:5d:77:f8:79:54:2f" "x509_certificate": "-----BEGIN CERTIFICATE-----MIIDezCCAuSgAwIBAgIJAMzy+weDPp7qMA0GCSqGSIb3DQEBBQUAMIGGMQswCQYDVQQGEwJBVTEMMAoGA1UECBMDTlNXMQ8wDQYDVQQHEwZTeWRuZXkxGjAYBgNVBAoTEU1hZXN0cmFubyBQdHkgTHRkMRYwFAYDVQQDEw1tYWVzdHJhbm8uY29tMSQwIgYJKoZIhvcNAQkBFhVzdXBwb3J0QG1hZXN0cmFuby5jb20wHhcNMTQwMTA0MDUyMzE0WhcNMzMxMjMwMDUyMzE0WjCBhjELMAkGA1UEBhMCQVUxDDAKBgNVBAgTA05TVzEPMA0GA1UEBxMGU3lkbmV5MRowGAYDVQQKExFNYWVzdHJhbm8gUHR5IEx0ZDEWMBQGA1UEAxMNbWFlc3RyYW5vLmNvbTEkMCIGCSqGSIb3DQEJARYVc3VwcG9ydEBtYWVzdHJhbm8uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+2uyQeAOc/irohCyT33RkkWfTGeJ8E/mu9F5ORWoCZ/h2J+QDuzuc69Rf1LoO4wZVQ8LBeWOqMBYzotYFUIPlPfIBXDNL/stHkpg28WLDpoJM+46WpTAgp89YKgwdAoYODHiUOcO/uXOO2i9Ekoa+kxbvBzDJf7uuR/io6GERXwIDAQABo4HuMIHrMB0GA1UdDgQWBBTGRDBTie5+fHkB0+SZ5g3WY/D2RTCBuwYDVR0jBIGzMIGwgBTGRDBTie5+fHkB0+SZ5g3WY/D2RaGBjKSBiTCBhjELMAkGA1UEBhMCQVUxDDAKBgNVBAgTA05TVzEPMA0GA1UEBxMGU3lkbmV5MRowGAYDVQQKExFNYWVzdHJhbm8gUHR5IEx0ZDEWMBQGA1UEAxMNbWFlc3RyYW5vLmNvbTEkMCIGCSqGSIb3DQEJARYVc3VwcG9ydEBtYWVzdHJhbm8uY29tggkAzPL7B4M+nuowDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQAwRxg3rZrML//xbsS3FFXguzXiiNQAvA4KrMWhGh3jVrtzAlN1/okFNy6zuN8gzdKDYw2n0c/u3cSpUutIVZOkwQuPCMC1hoP7Ilat6icVewNcHayLBxKgRxpBhr5Sc4av3HOW5Bi/eyC7IjeBTbTnpziApEC7uUsBou2rlKmTGw==-----END CERTIFICATE-----" }, # ===> Data Sharing # This section describes how to configure the Account and Connec!™ webhooks # => 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. "connec": { "host": "https://api-connec.maestrano.com" } "webhook": { # # 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 (required) # => group_users_path (required) "account": { "groups_path": "/maestrano/account/groups/:id", "group_users_path": "/maestrano/account/groups/:group_id/users/:id" }, # ==> Connec Subscriptions/Webhook # The following section is used to configure the Connec!™ webhooks and which entities # you should receive via webhook. # # "connec": { # => 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 # "notifications_path": "/maestrano/connec/notifications", # => subscriptions (required) # This is the list of entities (organizations, people, invoices etc.) for which you want to be # notified upon creation/update in Connec!™ # "subscriptions": { "accounts": true, "company": true, "events": false, "event_orders": false, "invoices": true, "items": true, "journals": false, "organizations": true, "payments": false, "pay_items": false, "pay_schedules": false, "pay_stubs": false, "pay_runs": false, "people": true, "projects": false, "tax_codes": true, "tax_rates": false, "time_activities": false, "time_sheets": false, "venues": false, "work_locations": false } } } } |
1.3 Required fields
Required fields in your metadata, depending on the SSO protocol you have chosen:
Field | OpenID | SAML |
---|---|---|
environment | ||
app.host | YES | YES |
api.id | YES | YES |
api.host | YES | YES |
sso.idm | ||
sso.init_path | YES | |
sso.consume_path | YES | |
sso.idp | YES | |
sso.x509_fingerprint | YES | |
sso.x509_certificate | YES | |
connec.host | YES | YES |
webhook.account.group_path | YES | YES |
webhook.account.group_users_path | YES | YES |
webhook.connec.notifications_path | YES | YES |
wenhook.connec.subscriptions | YES | YES |
...
2 - Single Sign-On
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
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
...
More high level resources can also be found on this wiki, under the Connec!™ API V2 section: Connec!™ API V2 documentation
groups_path