Prerequisites for the Web API

Dentrix Enterprise's Web API is the only API that can be used for Meaningful Use Stage 3 (MU3) attestation with Dentrix Enterprise. The Web API is accessible via Apigee Edge. Apigee Edge enables secure access to Dentrix Enterprise with a well-defined API. Apigee Edge acts as a proxy (an abstraction layer that "fronts" for the API) and provides value-added features, such as security, rate limiting, quotas, and analytics.

Note: No additional software or configurations are required on the client side in order to be able to successfully interact with the API.

Authorization on the Apigee Edge Server

The Apigee Edge server uses OAuth 2.0 to limit an access to the API endpoints.

The following diagram illustrates how resources are accessed with Apigee Edge serving as the authorization server. In this scenario, Edge is also the resource server (the API endpoints are the protected resources).

• Client App - The app that needs access to the user's protected resources. Typically, in this scenario, the app runs on a server rather than locally on a user's laptop or computer.
• Apigee Edge - In this scenario, Apigee Edge is the OAuth authorization server. Its role is to generate access tokens, validate access tokens, and pass authorized requests for protected resources on to the resource server.
• Resource Server - The backend service that stores the protected data that the client app needs permission to access. If you are protecting API endpoints hosted on Apigee Edge, Apigee Edge is also the resource server.

Granting Access to the API

The following is a summary of the steps required to grant access to the protected API with Apigee Edge serving as the authorization server.

Note: In this scenario, the client app simply presents its client ID and client secret, and if they are valid, Apigee Edge returns an access token.

Prerequisite: The client app must be registered with Apigee Edge to obtain the client ID and client secret keys. See "Registering an Application in Apigee" and "Registering a Client (Organization) in Apigee" below for details.

1. The client requests an access token. To receive an access token, the client POSTs an API call (accesstoken) to Edge with a client ID and a client secret, which can be obtained from a registered developer app. In addition, grant_type=client_credentials must be passed as a parameter of the query.
2. Edge validates the credentials. This endpoint validates the app's credentials.
3. Edge returns a response. If the credentials are validated, Edge returns an access token to the client; if not, an error is returned.
4. The client calls the protected API. Now, with a valid access token, the client can make calls to the protected API. In this scenario, requests are made to Apigee Edge (the proxy), and Edge is responsible for validating the access token before passing the API call along to the target resource server.

Registering an Application in Apigee

An Apigee administrator (Wood, Bart <bart.wood@henryschein.com> or Hecht, Tim <tim.hecht@henryschein.com>) uses the Apigee administration portal to create an Apigee app. The administrator securely shares the app's Oauth client id and Oauth secret with the client.

Registering a Client (Organization) in Apigee

A client provides an Apigee administrator with a domain name/URL for the resource server. The administrator sets up a unique identifier per organization (such as a name/id) and a domain name/URL that points to where Apigee can reach the organization's data. Then, the administrator associates the client with the organization in the Org Mapper service.

The client will need to use the Oauth client id + secret + unique Org ID provided for all requests. The Apigee layer authenticates a request using the client id and secret, verifies that the client has access to the requested unique Org ID, and then routes the request to the domain name/URL registered for the organization.