API Authentication

• The Provider would then provide their credentials (Accuro Login Credentials)
• The Provider will be asked to approve or deny the client application access to the resources and offices.
• If the resource owner approves, the authentication server will then redirect to the redirect_uri provided and registered to the client and include the code as a query parameter.
• The client must then request an access token from the authentication server using the code provided in the previous step. This code can only be used ONCE and expires in no longer than 10 minutes.
• The access token is requested similar to how a client credentials grant works:

Response:

The access token can then be used for subsequent resource requests.

Notes:

• The request must be a POST
• The token call uses basic authentication with the client_id and client_secret as username/password
• The grant_type parameter must be present in the body and must have the value of authorization_code
• The code parameter must be present in the body and must have the value provided in the query parameters of the redirection from user approval.
• The value of the code parameter can only be used ONCE and expires quickly
• The redirect_uri parameter must be present in the body and must have an identical value to the redirect_uri used in previous steps

When the access_token is about to expire, the refresh_token can be used to request a new access_token

The specification for Refreshing access_tokens can be found here.

Refreshing a token is similar to requesting the access_token

The steps to refresh authentication

• The application will make a call to the token url including the refresh token provided
• The application will extract the new access_token from the result and use it on subsequent resource requests

Example:

Response:

Notes:

• The request must be a POST
• The token call uses basic authentication with the client_id and client_secret as username/password
• The grant_type parameter must be present in the body and must have the value of refresh_grant
• The refresh_token parameter must be present in the body and must have a valid refresh token bound to the requesting client_id

Authentication Grant

The Patient Authentication flow is essentially an Authorization Grant flow (similar to Provider Authentication) using an alternate Authentication Server and requiring a token exchange. Patient Authentication allows access to end points exposing patient information for the authenticated patient such as:

• Demographics
• Labs
• Appointments

Pre-Conditions and Notice

• A Precondition to this Authentication method is some sort of ‘out-of-band’ linking of an IDP User to an Accuro Patient.
  • One example of this would be to install Stargate, enable the Medeo module, and have a patient create an appointment and then link the Accuro Patient to the Medeo Patient
  • Another example would be however Medeo Patients are looked up and added for Medeo Messaging.
  • To Note: The above two flows might need some small tweaks to ensure that the linking of Accuro Patient to IDP user is working properly (i.e. Tickets and development).
• On top of this, the current implementation of patient authentication described below is temporary. Eventually it will be replaced with a simple Authentication flow similar to the Provider Flow above.

The steps to authenticate are:

• Client application directs the resource owner (patient user) to the authorization server login
• The Patient User will authenticate with their credentials.
• If the Patient User authenticates, the authentication server will then redirect to the redirect_uri provided and registered to the client and include the code as a query parameter.
• The client must then request an access token from the authentication server using the code provided in the previous step. This code can only be used ONCE and expires in no longer than 10 minutes.
• The authorization server responds with an access token.
• In the future, this will end the Patient Authentication Flow, and the access token returned by the above call will be useable for future calls But for now there are some extra steps.
• The client application must then convert the access_token from IDP to a Rest API Access token.
• The client application will need to obtain a client credentials grant from the Rest API. See the instructions above.
• The client application must then make a post to:
  http://<host>:<port>/accapi/rest/v1/portal/token?officeId=<officeId>
  
• The client application must include the access_token bare in the request body with a content type of application/json
• The client application must include the officeId as a query parameter.
• The access_token and refresh_token can then be extracted from the response body and used on subsequent requests (including refresh).

Example:

• Client Application Directs the Patient User to the Authentication Server login page below:

• If authentication is successful, the client application will be redirected to the redirect_uri provided, with the code query parameter.
• The client saves the code parameter and ignores other parameters.
• The client must then request an access token from the authentication server using the code provided in the previous step. This code can only be used ONCE and expires in no longer than 10 minutes.
• The client application then requests an access_token similar to flows described previously.

Response:

• The client application must now request an access token from Rest API Authentication Server for this patient.
• The client should store the access_token returned in the body of the above request
• The client should obtain a client credentials grant from the Rest API using the instructions above.
• The client should make a post to the Rest API with the access_token in the body:

Response: