Summary

The Net Health API authenticates via the OpenID Connect protocol. Our OpenID Provider (OP) is our Net Health Accounts site. After registering with our OP, you can obtain a token that can be used to access the Net Health API.

To learn more about the OpenID Connect protocol, view the specifications.

The configuration page for the OP can be found here.

Guide

1. Register your application with the Net Health Accounts site.

Visit the Net Health Accounts site to register your application. Registration can be done through the /api/Clients/Register action. More information can be found on the Help page of the Net Health Accounts site.

Once registered, you will be given a client ID and client secret that are known to both Net Health and your application. The client ID and secret will be used to identify your application to the Net Health Accounts site.

2. Obtain an access token from the Net Health Accounts site.

Before your application can access data from a Net Health API endpoint, it must obtain an access token that grants access to that API endpoint. The token includes a parameter named scope that controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

Requests require an authentication step where the user logs in with their account. That user may be you or it may be a user of your application that has an account affiliated with Net Health. After logging in, the user is asked to grant the permissions that your application is requesting. If the user grants the permission, the Accounts site will send your application an access token. If the user does not grant the permission, the site will return an error. Even if the user grants permission to your application, the user can choose to grant or deny access each scope individually.

3. Send the access token to an API.

After your application obtains an access token, it sends the token to a Net Health API endpoint in an HTTP authorization header.

Access tokens are valid only for the set of operations and resources described in the scope of the token request. Access tokens are permitted to be re-used until they expire.

4. Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to an API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. Refresh tokens should be stored securely. Refresh tokens also have an expiration, but they are alive much longer than access tokens.

Components or Configurations

No software components or configurations are necessary for an application to implement in order to be able to successfully interact with the API and process its response(s).