App Connection for HIMSA SSO

Using the access token issued by the IdP you will be able to retrieve information about the current user and account. If you want to retrieve a list of users in that account you will need to request an app connection.

Before the app can access the API it must initially request which level of access it needs to user account fields (e.g. FirstName, PhoneNumber) that must be accessible to the app allowing it to perform its intended behavior.

The app won’t be able to make use of the API before the request has been approved by a user.

Checking current data access

It is assumed that an app will retrieve its current access permissions soon after being launched by calling GET AppConnection/GetCurrentDataAccess.

If HTTP status code 404 Not Found is returned it means that the app has never been connected before.

The app should check whether the user account fields that it intends to use have already been requested, but is either denied or is still in pending approval state.

Requesting data access

The app requests access by specifying user account fields in the 'AppConnectionRequest’ data structure.

It is suggested to request commonly used permissions and include already granted permissions in the new request, in order not to remove access to features that the user has previously approved.

The information in the response ‘AppConnection’ received from the GetAppConnection call will allow the app to determine:

Whether the current user has permission to approve the request.
Where to redirect a web-browser in order for the user to approve the request.

An App can always request new permissions to access User Account Fields.
In case the App has a pending ‘AppConnection' for the Tenant it will be replaced by the latest 'AppConnection’.

Please observe that the data access requested by the App may be fully or partially granted.

Examples

Below is shown data structures followed by a sequence diagram where a user with the permission to approve requested access permission has launched an app.

AppConnectionRequest example:

{
	UserAccountAccessLevel: "Limited", ("Basic", "Advanced")
}

AppConnection example:

{
    AppConnectionId : {
		"6c9e1877-4299-4c4a-b88a-d42188c1cb15"
	},
	AppPortalUrl : {
		"https://portal.himsa-sso.com/ManageAppConnections/Approve?id=6c9e1877-4299-4c4a-b88a-d42188c1cb15"
	}
}

CurrentDataAccess example:

{
	UserAccountAccessLevels: [
		{
			Field: "Basic",
			Access: "Granted"
		},
		{
			Field: "Advanced",
			Access: "Denied"
		},
		{
			Field: "Limited",
			Access: "PendingApproval"
		}
	],
    Created: "2023-02-23T08:46:57.956Z"
}