Feature Highlight - Desktop API

Securing desktop applications is difficult. There’s only so much software companies can do when you can’t control the machine the application is installed on or who has physical access. Still, it's essential to do everything we can - especially when sensitive medical data is involved.

Enter our new API: the Halo Cloud Desktop API.

With stricter token-based auth, limited endpoint access, and the ability to integrate with existing auth systems used by desktop applications, it is designed to better protect practices and integrators from the risks surrounding desktop applications.

It also comes with some potential performance improvements.

Why do desktop applications need a different auth system?

Halo’s original cloud APIs were designed to be called from cloud infrastructure, such as Microsoft Azure or Amazon AWS. These services have layers upon layers of security measures built in, plus dozens more that can be configured as needed. This makes cloud infrastructure a relatively trustable environment, which means that “secure” auth patterns don’t tend to be as onerous as they otherwise could be.

Desktop applications have none of these protections. Software vendors have no control over the hardware the application is installed on, what other software exists on that machine, whether there are any security measures in place, or who has physical access. There are certainly best practices that should be followed, but when it comes to protecting patient data, it is important that we hope for the best and prepare for the worst.

That’s why the Desktop API’s auth system is so different.

What's the difference?

Halo’s existing API - what we call the Integrator API - uses subscriptions for authentication, data-level access controls for authorisation, sixteen-digit GUIDs for routing, plus a few extra safeguards.

The new Desktop API, in comparison, uses:

• Short-lived tokens and integrator-controlled device IDs for authentication, and
• Data-level access controls and GUIDS for authorisation at two different levels

It also introduces a token renewal workflow, to enable access expiries.

All up, this adds several new layers of security, while also ensuring that there is no reason for auth details for the Integrator API (namely the subscription details) to end up on end-user machines. That is another key benefit of having two different APIs with different auth systems for different use cases - separation.

Keeping things separate

To look at the bigger picture, here’s what this means for integrators using the Integrator and Device APIs:

• The Integrator API should only be used by cloud infrastructure, and the auth details used to communicate with it should only be securely stored within that cloud infrastructure.
• Desktop applications should only communicate with Halo’s Desktop API and the software vendor’s cloud infrastructure. Such applications should never contact the Integrator API, and should not contain the auth details for the Integrator API.
• Retrieving tokens for use with the Desktop API is part of the Integrator API. This should still not be done by the desktop application directly, but rather by the vendor’s cloud infrastructure on behalf of the desktop application.
• The tokens used with the Desktop API are also specific to the practice and application they were created for, ensuring that an application at one practice can’t query another by accident.
• The Desktop API also does not include any of the Integrator API’s metadata endpoints, so that an application at one practice can’t even look up another practice. The only requests that can be made via the Desktop API are database queries to the same practice.

Improving performance too

In addition to all the security improvements, using the Desktop API for desktop applications could have a performance improvement as well.

Currently, the recommended way for a desktop application to query Halo Cloud is to go through the integrator’s cloud. This adds an extra step in the journey, both there and back, which adds a small amount of extra overhead.

Using the Desktop API allows desktop applications to query Halo Cloud directly, removing that extra step and potentially adding a (small) performance improvement.

So what is the auth workflow?

Full technical documentation of the Desktop API’s auth workflow can be found in our docs. However, for a quick overview:

1. The integrator authenticates and onboards a new application. From that process, a Device ID should be assigned to the new application, which both the integrator's cloud and the desktop application should know. If an application has an existing device or user authentication workflow, the Device ID could come from this process.
2. The integrator’s cloud requests a Desktop API Token from the Get token API endpoint, and includes in the request the practice's Halo GUID and the application's Device ID.
3. Halo Cloud validates the identifiers and issues a token.
4. The Integrator's cloud provides the Desktop API Token to the desktop application.

The Desktop API Token is then used by the desktop application, in combination with its device ID, to authenticate the desktop application when sending queries.

The token will also need to be renewed periodically. The expiry of a specific token can be found in the relevant token request response, and renewal simply involves repeating at least steps 2-4.

Where should I start?

Use of the Desktop API is subject to approval by the PMS you wish to use it for - please reach out to your partner program contact to discuss!