Accounts

As an API gateway, the Morgen Sync Service needs to be able to access the accounts of the users of the services it aggregates. This is done by using OAuth2.0 in most cases. The Morgen Sync service is registered as an application with the services it aggregates. To operate on a third-party account (e.g. create an event via Google Calendar), the user must first grant the Morgen Sync service access to the account. This is done by the user being redirected to the third-party service's login page. After logging in, the user is redirected back to the Morgen Sync Service. The Morgen Sync service then has access to the account and can operate on it.

Supported services

The Morgen Sync service currently supports the following services:

Calendars

Provider Name	Provider Id
Google Calendar	`google`
Office 365 (Graph API)	`o365`
CalDAV (including iCloud, Nextcloud, ownCloud, etc.)	Coming soon

Contacts (coming soon)

Provider Name	Provider Id
Google Contacts	`google`
Office 365 (Graph API)	`o365`

Videoconferencing (coming soon)

Provider Name	Provider Id
Google Meet	`google`
Microsoft Teams	`teams`
Zoom	`zoom`

How to connect an account

To initiate the authorization process on behalf of a user, you first retrieve the provider Authorization URL from Morgen, then you redirect the user browser to that URL.

To obtain the Authorization URL, issue an authorized GET request as follows:

curl --request GET \
     --url https://sync.morgen.so/v1/integrations/:providerId/oauth/authorizationUrl?redirect_url=<REDIRECT_URL> \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <JWT>'

Parameter	Type	Default	Required	Description
`providerId`	Path	-	Yes	The id of the provider you want to connect (see table above).
`redirect_url`	Query	-	No	The URL to redirect the user to after the authorization process is complete. If not provided, a plain text message will be displayed to the user. In case of failure, the error message will be passed as query parameter, e.g. `<REDIRECT_URL>?error=...`

Morgen replies with an authorizationUrl as below in this example:

{
     "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=5ef323da-xxxx-xxxx-xxxx-xxxxxxxf&redirect_uri=https%3A%2F%2Fsync.morgen.so%2Fv1%2Fintegrations%2Fo365%2Foauth%2Fcallback&response_type=code&state=KQv-rNsqSybWIbhY-C6Ga&scope=openid%20email%20profile%20offline_access%20MailboxSettings.ReadWrite%20User.ReadWrite%20User.ReadBasic.All%20Contacts.ReadWrite%20Calendars.ReadWrite%20Calendars.ReadWrite.Shared&access_type=offline&prompt=consent""
}

You can then redirect the user to the provided URL where the user will be able to authenticate with the provider.

How to disconnect an account

To disconnect an account, issue an authorized POST request as follows:

curl --request POST \
     --url https://sync.morgen.so/v1/integrations/accounts/:accountId/disconnect \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <JWT>'

Parameter	Type	Default	Required	Description
`accountId`	Path	-	Yes	The id of the account to disconnect.

How to list the connected accounts of a user

To list the connected accounts of a user, issue an authorized GET request as follows:

curl --request GET \
     --url https://sync.morgen.so/v1/integrations/accounts/list \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <JWT>'

Here is an example response:

{
  "data": {
    "accounts": [
      {
        "id": "640a62c9aa5b7e06cf400000",
        "providerId": "87ee97f6-470f-426a-9b73-xxxxxxxxxx",
        "userId": "6010a263f9a7f30012200000",
        "clientId": "morgen",
        "providerUserId": "example@morgen.so",
        "providerUserDisplayName": "John Doe",
        "integrationId": "o365",
        "auth": {
          "mechanism": "oauth",
          "refreshTokenUpdatedAt": "2023-03-09T22:50:49.838Z",
          "accessTokenUpdatedAt": "2023-03-13T12:50:00.957Z"
        },
        "lastCheckedAt": "2023-03-13T12:50:01.371Z",
        "lastCheckedError": null,
        "requiresAuthentication": null,
        "createdAt": "2023-03-09T22:50:49.842Z",
        "updatedAt": "2023-03-13T12:50:01.372Z"
      },
    ]
  }
}

How to list the available providers

It is possible to obtain the list of available providers from the Morgen Sync service. Use this route to fetch metadata about the providers, such as the name, the id, the service logo, and the supported features.

To list the available providers, issue an authorized GET request as follows:

curl --request GET \
     --url https://sync.morgen.so/v1/integrations/list \
     --header 'accept: application/json' \

Notice that this route does not require authentication.

Here is an example response:

{
  "data": {
    "integrations": [
      {
        "id": "o365",
        "groups": [
          "calendars"
        ],
        "displayName": "Office 365",
        "authenticationType": "oauth",
        "authDescription": "We will redirect you to your browser for the authentication with Microsoft.",
        "description": "Manage your Office 365 calendar.",
        "priority": 1,
        "iconData": "PHN2ZyBmaWxsPSJub25lIiB..."
      }
      ...
    ],
    "groups": [
      {
        "displayName": "Video Conferencing",
        "type": "video"
      },
      {
        "displayName": "Tasks",
        "type": "tasks"
      },
      {
        "displayName": "Calendars",
        "type": "calendars"
      },
      {
        "displayName": "Webhooks",
        "type": "webhooks"
      }
    ]
  }
}

Authentication Calendars