SSO & Subscriptions Management APIs

Subscription Management API’s

Subscriptions Management APIs allows external applications to get authorised and securely access the products and Healthcode. Subscriptions gives access to products and features of Healthcode’s product suite. These APIs are used to get the plans, roles and features provided by a plan and the features assigned to a site using subscriptions.

Product Group is an information system bundle that deals with a specific dataset – for e.g., Practice Management System, Clearing Services, PPR, etc.

Product: holds the information about services, functionalities or UI pages that can be subscribed as plans. A feature can be restricted to be visible to users by enabling the ‘displayforcheckout’ flag in the table. In this case, though the feature is selected in a plan, its not visible to the user.

Subscription Plans are the subscription plans that a client/site/user can subscribe to – for e.g., Basic, Lite, Pro for ePractice.

A Product Plan maps to several Roles that one can perform by subscribing to the specific plan.
Management of Product Plans is handled centrally as part of the Subscription Management implementation.

A Product Group typically consists of one primary data-domain implementation and optionally one or more UI interfaces, each implementation forming a distinct Product. For e.g., the PPR product group consists of a PPR data-domain implementation that encapsulates the practitioner profiles data and exposes a number of APIs to operate on same, and separate UI implementations for Specialist View, Insurer View and Hospital View.
A given Product may offer multiple subscription options as defined by Product Plans.
Management of Product Groups and Products is handled centrally as part of the Subscription Management implementation.

Sites and Users can be assigned a set of Roles, typically from the subset depending on the subscription one has.

Product Features: are the primary and smallest building blocks of the access control mechanism. Features control access to the smallest logical operation, like viewing or updating specific section of a PPR profile.

Features are typically functional, like Manage Demographics, View Demographics and Manage Insurer Recognition features in this example. However, in some cases they can also be operational, like the Archive Old Profiles feature. Operational features can typically be used for creating operational Roles, which can then be assigned to a schedulable batch module that can use the access to perform the requisite housekeeping operations, say overnight.

Roles: represent distinct workflow or interfaces to which a client, site or user can be given access to – for e.g., Manage PPR Profile, View PPR Profile, Manage Insurer Recognition, etc.

Roles are a grouping of features which are granted by having the role.
Roles are logical blocks – so in effect, their structure can be altered without code change.
All features mapped to a Role are treated as a set, and either one has the grant to all features or none.
Set of features granted by roles are not mutually exclusive. Where a client/site/user has permission to multiple roles and a specific feature is removed from one role, the client/site/user may continue to have access to that feature if it was granted by another one of their roles

Introspect API

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/introspect' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json' 
--header 'SU-SiteId: HC02006'

Where,

Header Field	Type	Mandatory/ Optional	Description
SU-SiteId	String	O	SiteId that needs to be switched to

API needs to provide an access token in the Authorization header as a Bearer token.

Additionally, as mentioned above API accepts SU-SiteId as an optional header.

RESPONSE PROCESSING

If SU-SiteId HTTP header was supplied, the API verifies the current logged in user has access to the specific site.

If any verification fails during the API process,API returns below message in the response body with HTTP 400, Bad Request.

{
    "message":"error message",
    "code": 400
}

If logged-in user is not found in the generated authentication token, API returns the following message in the response body with HTTP 400, Bad Request.

{
    "message": "userId not found in authentication token",
    "code": 400
}

If we are using client credentials to generate authentication token, then client account is not found for the extracted client, API returns the following message in the response body with HTTP 422, Unprocessable Entity.

{
    "message": "No account is associated for this client",
    "code": 422
}

If client account is inactive, API returns below message in the response body with HTTP 422, Unprocessable Entity.

{
    "message": "The client account ${clientAccount} status should be ACTIVE",
    "code": 422
}

If SU-SiteId is not connected to logged-in user, API returns the following message in the response body with HTTP 403, Forbidden.

{
    "message": "The SU-Site ${SUSiteId} and SU-User ${UserId} authorisation is invalid",
     "code": 403
}

If SU-SiteId is inactive, API returns below message in the response body with HTTP 403, Forbidden.

{
    "message": "The SU-Site ${SUSiteId} status should be ACTIVE",
    "code": 403
}

If all verifications succeed, API returns below message in the response body with HTTP 200, Ok.

{
    "status": "success"
}

List Features API

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/feature' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json' 
--header 'SU-SiteId: HC02006'

Where,

Header Field	Type	Mandatory/ Optional	Description
SU-SiteId	String	O	SiteId optional header parameter

API needs to provide an access token in the Authorization header as a Bearer token.

Additionally, as mentioned above API accepts SU-SiteId as an optional header to validate the authorization for the site.

RESPONSE PROCESSING

The API returns the list of roles and the features associated with each roleId.

If any verification fails during the API process, the response format returned will be HTTP 400 Bad Request as shown below.

{
    "message":"error message",
    "code": 400
}

If logged-in user is not found in the generated authentication token, API returns the following message in the response body with HTTP 400, Bad Request.

{
    "message": "userId not found in authentication token",
    "code": 400
}

If features are not assigned to the logged-in user ID, API returns the following message in the response body with HTTP 403, Forbidden.

{
    "message": "Features not found",
    "code": 403
}

If all verifications succeed, API returns below message in the response body with HTTP 200, Ok.

{
        "roleId": "GenericLoginFunctions",
        "code": "GenericLoginFunctions",
        "name": "Generic Login Functions (Public)",
        "status": "active",
        "features": [
            {
                "id": "Login v1.0",
                "name": "Login v1.0",
                "code": "Login_1_0",
                "identifier": "Login_1_0",
                "description": "Allows a user to login with a valid login account ",
                "status": "active"
            },
            {
                "id": "Reset Password v1.0",
                "name": "Reset Password v1.0",
                "code": "ResetPassword_1_0",
                "identifier": "ResetPassword_1_0",
                "description": "Allows a user to reset their password",
                "status": "active"
            }
        ],
        "clientassignable": false,
        "siteassignable": false,
        "userassignable": false,
        "accountmanagerassignable": false,
        "publicaccess": true,
        "productGroup": {
            "id": "PGwTCEK7",
            "name": "SSO and Subscriptions",
            "identifier": "SUBSCRIPTION",
            "description": "central subscription management PRODUCT GROUP"
        },
        "createdby": "011LR1BQN"
    }

Where,

Field	Type	Description
roleId	String	logged-in User role
code	String	logged-in User key
name	String	logged-in User name
status	String	logged-in User status
features	String	logged-in User features

Get User Info API

REQUEST

curl --location --request GET 'https://accounts.dev.healthcode.co.uk/api/userinfo?
code=3PWqF40zaKcU3t9vZF4APpotS' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer {{AccessToken}}' 
--data-raw ''

Where,

Request Parameter	Mandatory/Optional	Description
code	M	Code to retrieve the user site’s selection

API needs to provide an access token in the Authorization header as a Bearer token.

Code will be generated from product and service page and passed as path parameter to this API to get user and site info.

RESPONSE PROCESSING

If the code is invalid, API returns the following message in the response body with HTTP 422, Unprocessable Entity.

{
   "message":"Secret code not found",
   "code": 422
}

If all verifications succeed, API returns the following JSON in the response body with HTTP 200 OK.

{
    "user": {
        "id": "HUPYAOWP",
        "title": "General",
        "family": "ab",
        "given": "Ab",
        "middlename" : "john",
        "loginEmailAddress": "karris@healthcode.co.uk",
        "manageSubscriptions": [],
        "roles": [],
        "creationdate": "2023-03-23 14:29:28",
        "lastupdatedon": "2024-02-19 11:22:08"
    },
    "homesite" : {
         "id" : "HC15191",
         "name" : "parinkia"
     },
    "site": {
        "id": "HC010A0",
        "name": "Jero Ignore ESTV",
        "type": "p"
    }
}

Where,

Field	Type	Description
id	String	logged-in User record
title	String	logged-in User title
family	String	logged-in User family
given	String	logged-in User given by
loginEmailAddress	String	logged-in User email address
manageSubscriptions	String	logged-in User Subscription Details
site	String	logged-in User sites
homesite	String	id=siteId name=sitename

List Authorised Sites API

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/restricted/site/v1/authorised' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json'

API needs to provide an access token in the Authorization header as a Bearer token.

API returns list of active sites assigned to the logged-in user.

RESPONSE PROCESSING

If all verifications are succeed, API returns below message in response body with HTTP 200 Ok Entity.

[
    {
        "id": "HC00009",
        "name": "NewSite660",
        "identifier": "HC00009",
        "status": "ACTIVE",
        "type": "m",
        "parentsite": {
            "id": "HCODE"
        }
    },
    {
        "id": "HCODE",
        "name": "Healthcode",
        "identifier": "HCODE",
        "status": "ACTIVE",
        "type": "h",
        "parentsite": {
            "id": "HCODE"
        }
    }
]

Where,

Field	Type	Description
id	String	Site ID
name	String	Site Name
description	String	Site Description
status	Boolean	Site Status
type	String	Site Type (code) Below are the site type codes c = Practice g = Group h = Healthcode i = Insurer m = Medical Secretary p = Provider s = Practitioner t = Hospital
parentsite	String	Parent Site ID

List Authorised Sites API – V2

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/restricted/site/v2/authorised?pageNumber=1&maxRecordsPerPage=100&search=HC0' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json'

Where,

Request Parameter	Type	Mandatory/ Optional	Description
pageNumber	Integer	O	page number for the pagination
maxRecordsPerPage	Integer	O	maximum number of records for each page
search	String	O	site Id/site Name of the site which we want to search in the list

API needs to provide an access token in the Authorization header as a Bearer token.

Additionally, as mentioned above API accepts request parameters which are optional.

pageNumber parameter is used to get the details of particular page.

maxRecordsPerPage parameter is used to limit the maximum number of records for every page.

search parameter is used to search for particular site details by providing site Id or site Name as search value.

API returns list of sites assigned to the user and also their child sites for logged-in user and also pagination details related to list of sites returned.

RESPONSE PROCESSING

If all verifications are succeed, API returns below message in response body with HTTP 200 Ok Entity.


    {
    "pagination": {
        "totalRecords": 6324,
        "currentPage": 1,
        "totalPages": 64,
        "nextPage": 2,
        "prevPage": null
    },
    "sites": [
        {
            "id": "HC011XD",
            "name": "Natalie Dunlop Single Specialist",
            "identifier": "HC011XD",
            "status": "ACTIVE",
            "type": "p",
            "parentsite": {
                "id": "HCODE"
            }
        },
        {
            "id": "HC010FJ",
            "name": "Pauls Provider Site",
            "identifier": "HC010FJ",
            "status": "ACTIVE",
            "type": "i",
            "parentsite": {
                "id": "HCODE"
            }
        },
        {
            "id": "HC00JWI",
            "name": "Availability Nous",
            "identifier": "HC00JWI",
            "status": "ACTIVE",
            "type": "p",
            "parentsite": {
                "id": "HCODE"
            }
        }
}

Where,

Field	Type	Description
id	String	Site ID
name	String	Site Name
description	String	Site Description
status	Boolean	Site Status
type	String	Site Type (code) Below are the site type codes c = Practice g = Group h = Healthcode i = Insurer m = Medical Secretary p = Provider s = Practitioner t = Hospital
parentsite	String	Parent Site ID

List Site Subscriptions API

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/restricted/subscription' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json' 
--header 'SU-SiteId: HC02006'

Where,

Header Field	Mandatory/Optional	Description
SU-SiteId	M	Site ID

API needs to provide an access token in the Authorization header as a Bearer token.

Additionally, as mentioned above API accepts SU-SiteId as an mandatory header.

API returns the list of subscription plan records with id and name fields based on the supplied SU-SiteId.

RESPONSE PROCESSING

If the logged-in user doesn’t have access to the given site, API returns the following message in the response body with HTTP 403, Forbidden.

{
    "message": "Loggedin user does not have permission to perform this operation.",
    "code": 403
}

If all verifications succeed, API returns below message in the response body with HTTP 200, Ok..

{
    "siteId": "HC01163",
    "subscriptions":{
            "subscriptionId": "PSpC4XFQk9",
            "plan":{
                "planId": "PLEZDQDL",
                "planName": "Clearing Service 2 Days",
                "planDescription": "2 Days\nEnables electronic invoicing from a compliant Practice Management System",
                "planSlab": 1,
                "siteTypes":{
                     "code": "g",
                     "name": "Group"
                 },
                 {
                     "code": "h",
                     "name": "Healthcode"
                 }
            }
    }
}

Where,

Field	Type	Description
siteId	String	Site ID
subscriptionId	String	Subscription ID
planId	String	Plan ID
planName	String	Plan Name
planDescription	String	Description of the Plan
planSlab	Integer	Plan Slab
siteTypes	String	Site Types which are assigned to the Plan

Get User Details API

REQUEST

curl --request GET 
--url 'https://accounts.dev.healthcode.co.uk/api/restricted/user' 
--header 'Authorization: Bearer abCdE12...89mNopq0r' 
--header 'Content-Type: application/json' 
--header 'SU-UserId: HUXR8LM6'

Where,

Header Field	Type	Mandatory/ Optional	Description
SU-UserId	String	O	UserId for which details are required

API needs to provide an access token in the Authorization header as a Bearer token.

Additionally, as mentioned above API accepts SU-UserId as an optional header.

RESPONSE PROCESSING

If we are using client credentials, then SU-UserId is not provided in the header , API returns the following message in the response body with HTTP 422, Unprocessable Entity.

{
   "message": "SU-UserId is missing",
   "code": 422
}

{
   "message": "No account is associated for this client",
   "code": 422
}

If client account is inactive, API returns below message in the response body with HTTP 422, Unprocessable Entity.

{
    "message": "The client account ${clientAccount} status should be ACTIVE",
    "code": 422
}

If the client account doesn’t have access to the given user, API returns the following message in the response body with HTTP 403, Forbidden.

{
    "message": "The client account ${clientAccount} does not have access to this user ${userId}",
    "code": 403
}

This API returns user details and associated sites details whose status is “ACTIVE”. The userId will be retrieved from the access token.

{
    "userId": "HUPYAOWP",
    "title": "General",
    "firstName": "Ab",
    "lastName": "ab",
    "middlename" : "john",
    "loginEmailAddress": "karris@healthcode.co.uk",
    "status": "ACTIVE",
    "homesite" : {
         "id" : "HC15191",
         "name" : "parinkia"
     },
    "sites": [
        {
            "siteId": "HC00G57",
            "siteName": "Rivers Hospital",
            "description": "HC00G57 migrated from Veda",
            "siteType": "p"
        },
        {
            "siteId": "HC00GLR",
            "siteName": "A6 test",
            "description": "HC00GLR migrated from Veda",
            "siteType": "s"
        }
        
    ]
}

Where,

Field	Type	Description
userId	String	User ID
title	String	Title of the User
firstName	String	First Name of the User
lastName	String	Last Name of the User
loginEmailAddress	String	Login Email Address of the User
siteId	String	Site Id
siteName	String	Site Name
description	String	Description of the Site
siteType	String	Site Type (code) Below are the site type codes c = Practice g = Group h = Healthcode i = Insurer m = Medical Secretary p = Provider s = Practitioner t = Hospital
homesite	String	id = siteId name = sitename

OAuth API’s

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Access Token: An access token is a credential that allows clients to access protected resources. It represent authorizations issued by the resource owner and can specify scopes and access durations. It can either be an identifier to retrieve authorization information or self-contained with verifiable data and signatures.

Refresh Token: A refresh token is a credential used to obtain access token. It is issued to the client by the authorization server and is used to obtain a new access token when the current access token becomes invalid or expires, or it can also be used to obtain an additional access token with shorter lifetime and fewer permissions.

Logout Process

There are two ways to execute logout process. They are

Directly calling logout endpoint from the browser to clear tokens and session.
Calling revoke api and then back to prompt-login page.

1.Logout Endpoint

REQUEST

curl --request GET
--endpoint 'https://auth.dev.healthcode.co.uk/logout' 
--header 'Content-Type: application/json'

RESPONSE PROCESSING

If logout endpoint executed from browser successfully, then authorization server responds with HTTP status code 200 and this call removes the OAuth tokens & session which will force the user to log in again before invoking any protected API calls.

Note : Before executing logout endpoint , local storage should be cleared.

2.Revoke API

REQUEST

curl --request POST
--url 'https://auth.dev.healthcode.co.uk/revoke' 
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Basic c3Vic2NyaXB0aW9uOlBwazhVcl85bzlfZVBwTDRQLXNQd2VJMEFoLVh6eXpLTkNlSzVXQTZXNEVnR2tsSU9XNUZwam1nS2EzZzZ4TVBxMzQxbUY3M3E2QUE5MDJCZjFLYU1B'

--data-urlencode 'token=eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJST09UVVNFUiIsImF1ZCI6InN1YnNjcmlwdGlvbiIsImF1dGhfdGltZSI6MTcwODUyMjM2Miwia2lkIjoicnNhMSIsImlzcyI6Imh0dHA6XC9cL2xvY2FsaG9zdDo4MDg1XC9vcGVuaWQtY29ubmVjdC1oYy1vdmVybGF5LXNlcnZlci13ZWJhcHBcLyIsInNpdGVpZCI6IkhTMjNFUzJHLEhTM0lLRFdTIiwiZXhwIjoxNzA4NTIyMzk1LCJpYXQiOjE3MDg1MjIzOTAsImp0aSI6ImZhMzM1NzliLTQwYmQtNDkxNy05ZDgyLWZhNzJlNjY1MGMzYyIsImVtYWlsIjoiamFzaW1qYWJyaUBnbWFpbC5jb20iLCJlbWFpbHZlcmlmaWVkIjpmYWxzZX0.HZzCsjIl0pUYUTt5p_mEFeGf3whuAiaCHOUkarszoC4X6oUNYJ8g12rv'
--data-urlencode 'token_type_hint=access_token'

Where,

Field	Type	Mandatory/ Optional	Description
token	String	M	The token that the client wants to get revoked
token_type_hint	String	O	A hint about the type of the token submitted for revocation

API needs to provide Basic Auth in the Authorization header.

API needs token and token_type_hint in the request body. token_type_hint can be an access_token or refresh_token.

RESPONSE PROCESSING

If access_token is provided in the request , then it will revoke access_token.

If refresh_token is provided in the request, then it will revoke refresh_token and access_token.

If the token has been revoked successfully, then authorization server responds with HTTP status code 200.After that user will be redirect to prompt-login again before invoking any protected API calls.

Get Event Info API

REQUEST

curl --location --request GET 'https://accounts.dev.healthcode.co.uk/api/event?
sns_id=6662a403-2b71-5bb5-b7b4-fb26ffac042b' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer {{AccessToken}}' 
--data-raw ''

Where,

Request Parameter	Mandatory/Optional	Description
sns_id	M	sns_id to retrieve the event details

API needs to provide an access token in the Authorization header as a Bearer token.

The sns_id will be generated during the event creation or update process and passed as a path parameter to this API to retrieve event information

RESPONSE PROCESSING

If the sns_id provided as a path parameter is invalid, the API will return a response with HTTP 403 (Forbidden) and the following message in the response body.

{
    "message": "SNS_ID is Invalid.",
    "code": 403
}

If all verifications are successful, the API will return the event details along with the corresponding transaction details in the response JSON, with an HTTP 200 (OK) status.

The response JSON attribute resource contains the details of the respective transaction module

{
    "eventId": 23,
    "eventStatus": "NOTIFIED",
    "eventType": "SITE_CREATED",
    "resource": {
        "id": "HC12084",
        "name": "Site Event 3",
        "creationDate": "2023-05-08 14:37:24",
        "createdBy": "011LR1BQN",
        "isSyncWithSalesforce": false
        "account": {
            "id": "HATGZQCD",
            "name": "Testing22 sdsf test",
            "status": "ACTIVE",
            "isAccountManager": false,
            "isSyncWithSalesforce": false,
            "is2FaEnforced": false
        },
        "parentSite": {
            "id": "HCODE",
            "name": "Healthcode",
            "status": "ACTIVE",
            "type": "h",
            "isSyncWithSalesforce": false
        }
    }
}