Prerequisites for using the welcome IP cloud API

The welcome IP cloud API is capable accessing the door entry system access points of end users when they are connected to the cloud. For this, a few prerequisites have to be met, some for the end user that owns the door entry device(s) (e.g. the smart access point, or “SmartAP”) and some for the developer that is using the welcome IP cloud API.

Topology

3rd party App we mean a mobile APP or PC software connected to a third party cloud.

The integration shall be done through the myBuilding Portal which allows to send push notifications to the 3rd Party App.

The prefered communication for the step is to enable this feature by an cloud to cloud communication. Which means the SI/Installer need to access this myBuilding Service by an own cloud based solution.

End user

This cloud API is currently only capable of accessing systems that are connected to the ABB myBUILDINGS cloud.

Additionally the end user must enable the welcome IP API support setting in the SmartAP settings, found under “Preferences” → “Connection & APIs” →
“MyBuildings connection". Multiple SmartAPs can be added to the same account.

The end user needs an ABB-welcome IP smart access point with version 6.36 or later.

To sum up, the end user/smart access point requirements are:

  • A smart access point with at least version 6.36 must be available.
  • The end user must have a ABB myBUILDINGS/myBUSCH-JAEGER account.
  • The smart access point must be connected to the myBUSCH/myBUSCH-JAEGER cloud with that account.
    This can be done by visiting “Preferences” → “Connection & APIs” →
    “MyBuildings connection" on the smart access point with a browser.

Endpoint/Authentication

You can use one of the following approaches to get a token

Base Auth

(using MyBuildings-user credentials) on the following endpoint in the targeted environment

prod: POST https://api.eu.mybuildings.abb.com/user/access-token
stage: POST https://api.eu.mybuildings.abb.com/user/access-token

OAuth

(see also https://eu.mybuildings.abb.com/en/documentation/sso)

{ 
"authorize_url": https://eu.mybuildings.abb.com/sso/authorizeresponse_type=code&client_id=c7117538-ea49-4a2e-8121-9bf550e44da0&state=eyJhbGci[...]", 
"code_url": https://api.eu.mybuildings.abb.com/external/oauth2helper/code/get/c7117538-ea49-4a2e-8121-9bf550e44da0?state=eyJhbGci[...]", 
"accesstoken_request_url": "https://eu.mybuildings.abb.com/sso/token" 
}
  • Open "authorize_url" in Browser and let user login-in
  • Request code via: GET on "code_url" - result eg. {"code":"e7dd[...]"}
  • Request token: POST on "accesstoken_request_url with "x-www-form-urlencoded"
 grant_type:authorization_code 
 scope:RemoteControl Monitoring RegisterDevice 
 code:[insert "code" here] 
 client_id:c7117538-ea49-4a2e-8121-9bf550e44da0 client_secret:aXmWQSRkScPqH2mzPlrOIL0q4GMYoAp+OguxchI6
  • Handle result
{
 "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6[...]",
 "expires_in": 3600,
 "token_type": "bearer",
 "scope": "RemoteControl Monitoring RegisterDevice",
 "refresh_token": "3a76ec50afcd44e3dbbbc073b718322e8f7c89c2"
 }
  • Consider to plan token refresh after "expires_in" (in sec) - POST on "accesstoken_request_url with " x-www-form-urlencoded"
grant_type:refresh_token
refresh_token:[insert "refresh_token"]
client_id:"c7117538-ea49-4a2e-8121-9bf550e44da0"  client_secret:"aXmWQSRkScPqH2mzPlrOIL0q4GMYoAp+OguxchI6"
  • use token in GraphQL
    • e.g as HTTP Header in Playground: { "authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6[...]"}
    • or similarly in HTTP POST requests