OAuth 2.0

Our APIs use OAuth 2.0 protocol for authentication and authorization. We support base OAuth 2.0 scenarios for client-side applications.

To begin, please submit your information through our contact form at https://www.healthgorilla.com/#contact or contact your customer success manager to obtain OAuth 2.0 credentials for your organization.

📘

Transport Layer Security

All HealthGorilla endpoints are accessible only over SSL/TLS1.2+, plain HTTP calls are refused.

Resources

• OAuth 2.0 home page - http://oauth.net/2/
• Protocol Specification - http://tools.ietf.org/html/rfc6749

1. Obtaining OAuth 2.0 credentials

You must request OAuth 2.0 credentials from Health Gorilla to be able to make OAuth 2.0 requests. Please submit your information through your customer success manager or our contact form at https://www.healthgorilla.com/#contact.

In order to obtain the credentials you will need to provide the following info:

You will get back the following informatio:

2. Getting an Access Token

To access Health Gorilla APIs, you must obtain an access token that is issued to grant access to the requested APIs. A single access token can be used to access multiple APIs and access is identified by the Scopes variable linked to your specific token issued by Health Gorilla. When your application requests an access token, the request should contain the desired scopes; you will be able to request access only within the scopes that were allowed for you client application during registration.

There are several ways to get an access token from our OAuth 2.0 authorization server. They vary based on the type of client application and you can choose the one that applies to your application. Below you can find examples describing two possible authorization flows. More details can be found in OAuth 2.0 protocol specification.

Available authorization flows are:

1. JWT Bearer Token Grant
2. Authorization Code Grant
3. Implicit Grant

Health Gorilla OAuth 2.0 authorization endpoint is:

https://api.healthgorilla.com/oauth/authorize

To start, the client should send HTTP GET request to Health Gorilla OAuth 2.0 authorization endpoint. The request depends on the chosen authorization flow.

The following table lists common parameters for the authorization request:

Also, it is recommended to include additional parameters that are described in Section 2.4

Notes:

• The access token has a limited lifetime and will expire after some time of inactivity. Also, the resource server may invalidate access token to force the client to repeat authorization. If refresh token has been issued by the authorization server, then the application can request new access token (with the same grants) without authorization. Otherwise, the client application should go through the authorization flow again.
• You can always validate an access token using Health Gorilla info endpoint (see Section 4.
• An access token can be manually revoked using Health Gorilla revoke endpoint (see Section 5.

2.1. JWT Bearer Token Grant

HealthGorilla supports JSON Web Token (JWT) Bearer token authorization grant type for OAuth 2.0.

JWT Bearer token grant is usually used when the remote service needs to obtain an access token without user intervention. A trusted relationship between the services must be established prior to this method utilization.

Specifications:

• Assertion Framework - https://tools.ietf.org/html/rfc7521
• JSON Web Token - https://tools.ietf.org/html/rfc7523

2.1.1. Issue JWT

JWT token must contain the following claims:

JWT token must contain the following header parameters:

JWT must be signed with Client Secret that you received from Health Gorilla support after registration using HS256 (HMAC using SHA-256) algorithm.

2.1.2. Request

The web server should send an HTTP POST request to Health Gorilla OAuth 2.0 token endpoint to obtain an access token and a refresh token and include JWT with a request.

HTTPS POST request should have the following parameters:

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: api.healthgorilla.com 
Content-Type: application/x-www-form-urlencoded 
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&
client_id=qpgW44& 
scope=user%2F*.*&
assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. 
J9l-ZhwP[...omitted for brevity...].
eyJpc3Mi[...omitted for brevity...]

📘

Sandbox access token

Get your Sandbox access token on our API Reference page.

2.1.3. Response

Health Gorilla OAuth 2.0 Token Service returns the response as a JSON array.
You can find more details here - 2.2.5. Access Token Response.

2.2. Authorization Code Grant

This is a two-step authorization flow used to obtain both access tokens and refresh tokens and is optimized for confidential web server applications.

2.2.1. Authorization Request

The first HTTP GET request should be sent to Health Gorilla OAuth 2.0 authorization endpoint.

The set of supported query string parameters are:

This is recommended to include additional parameters described in Section 2.4.

Below you can find an example of the request:

https://api.healthgorilla.com/oauth/authorize? 
  response_type=code&
  client_id=qpgW44&
  redirect_uri=https%3A%2F%2Fmy-oauth2.com%2Fcallback&
  scope=place_orders&
  state=127&
  hg_user_first_name=Tom&
  hg_user_last_name=Sawyer
  [email protected]

2.2.2. Authorization Response

HealthGorilla OAuth 2.0 Authorization Server will return an authorization code if the user is authenticated and has been granted the requested access rights. The response will be sent to redirect_url that was passed in the request (or to the default callback if the redirect_url was omitted). The response contains an authorization code and the state parameter (if present).
Below you can find an example of that response:

https://my-oauth2.com/callback? 
  code=JDsd2jd24dsfDDFfd43r&
  state=127

When the client web server receives the authorization code, it must call Health Gorilla token endpoint to exchange its authorization code for an access token. Go to Section 2.1.4 to continue.

2.2.3. Authorization Error Response

If the authorization request was rejected or if any errors occurred, the authorization server returns an error response to the client.

Authorization Server returns an error code response in two ways:

• If the OAuth client (client_id) has not been authorized or callback URL (redirect_url) is invalid, then the server returns a response with HTTP status 400.
• Otherwise, the authorization server sends an error response to redirect_url.

An example of the error response:

https://my-oauth2.com/callback? 
  error=invalid_scope&
  state=127

2.2.4. Access Token Request

Once the authorization token is received, the webserver should send an HTTP POST request to Health Gorilla OAuth 2.0 token endpoint to obtain an access token and a refresh token.

You can find Health Gorilla OAuth 2.0 token endpoint description in Section 3.

HTTP POST request should have the following parameters:

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: api.healthgorilla.com 
Content-Type: application/x-www-form-urlencoded 
grant_type=authorization_code&
code=JDsd2jd24dsfDDFfd43r& 
client_id=qpgW44& 
client_secret=eeVk7vcq& redirect_uri=https%3A%2F%2Fmy-oauth2.com%2Fcallback

2.2.5. Access Token Response

Health Gorilla OAuth 2.0 Token Service returns a response as a JSON object.

A successful response contains the following fields:

Below you can find an example of the successful response:

{ 
  "access_token": "sldfksgkkG78df78dgfjhnfknkn", 
  "expires_in": 3600, 
  "token_type": "Bearer",
  "refresh_token": "HKj87975vlJjkjhfH766",
  "scope": "place_orders"
}

An error response contains the following fields:

Below you can find an example of the error response:

{ 
  "error": "invalid_grant", 
  "error_description": "Invalid authorization code", 
}

2.3. Implicit Grant

The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI.
Usually this method is used by JavaScript-based applications that cannot keep a secret.

2.3.1. Request

The first HTTP GET request should be sent to Health Gorilla OAuth 2.0 authorization endpoint.

The set of supported query string parameters are:

Also, this is recommended to include additional parameters that are described in Section 2.4.

Below you can find an example of that request:

https://api.healthgorilla.com/oauth/authorize? 
  response_type=token&
  client_id=qpgW44&
  redirect_uri=https%3A%2F%2Fmy-oauth2.com%2Fcallback&
  scope=place_orders&
  state=86&
  hg_user_first_name=Sarah&
  hg_user_last_name=Connor&
  hg_user_dob=01/01/1966

2.3.2. Response

Authorization server returns an access token as the result of the authorization request, if the user is authenticated and grants requested access rights. The authorization server redirects the user-agent back to the client using the “redirect_uri” provided earlier. The redirection URI includes the access token in the URI fragment.

A successful response contains the following fields:

Below you can find an example of that response:

https://my-oauth2.com/callback# 
  access_token=2YotnFZFEjr1zCsicMWpAA&
  token_type=Bearer&
  expires_in=3600&
  scope=place_orders&
  state=86

Once the access token is received in that way, it should be validated using Health Gorilla Info endpoint. Tokens received on the fragment must be validated to prevent confused deputy attacks.

2.3.3. Error Response

If the authorization request was rejected, or if any error occurred, then the authorization server returns an error response to the client. The authorization server can do it in two ways:

• If OAuth client (client_id) has not been authorized, or callback URL (redirect_url) is invalid, then the server returns an HTTP response with status HTTP 400 to the client.
• Otherwise, the authorization server sends an error response to redirect_url.

This is an example of that error response:

https://my-oauth2.com/callback# 
  error=access_denied&
  error_description=Canceled%20by%20the%20user&
  state=86

2.4. Extended authentication parameters

Health Gorilla Authorization Server extends OAuth 2.0 protocol. We define additional parameters the client can specify to speed up authorization for user-faced flows. Application can send these parameters if the client knows the user who is trying to authenticate. It is an optional part, but recommended.

Here you can find the set of additional parameters:

3. Refreshing the Access Token

If the authorization server issued a refresh token to the client, then the client can make a refresh request to the token endpoint to obtain a new access token. The newly issued access token will have the same permissions as the previous one, so the scope cannot be extended. The authorization server may return a new refresh token to use in further requests. The refresh token has fixed lifetime, and request may be rejected by the server. In this case, the client should send a new authorization request.

Health Gorilla OAuth 2.0 token endpoint is:

https://api.healthgorilla.com/oauth/token

3.1. Request

Client should send HTTP POST request to Health Gorilla OAuth 2.0 token endpoint.

HTTP POST request must contain the following parameters:

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: api.healthgorilla.com 
Content-Type: application/x-www-form-urlencoded 
grant_type=refresh_token&
client_id=qpgW44& 
client_secret=eeVk7vcq&
refresh_token=HKj87975vlJjkjhfH766

3.2. Response

Health Gorilla OAuth 2.0 Token Service returns response as a JSON array.

A successful response contains the following fields:

Below you can find an example of successful response:

{ 
  "access_token": "sldfksgkkG78df78dgfjhnfknkn", 
  "expires_in": 3600, 
  "token_type": "Bearer",
  "refresh_token": "HKj87975vlJjkjhfH766",
  "scope": "place_orders",
}

An error response contains the following fields:

Below you can find an example of the error response:

{ 
  "error": "invalid_grant", 
  "error_description": "Invalid refresh token", 
}

4. Validating the Access Token

Sometimes the client may need to validate an access token, for example to resolve confused deputy problem. Health Gorilla provides service that allows to verify the given access token.

Health Gorilla OAuth 2.0 Info endpoint is:

https://api.healthgorilla.com/oauth/info

For validating, the application should make the request to the endpoint and pass the desired access token in the access_token parameter.

Below you can find an example of such a request:

https://api.healthgorilla.com/oauth/info?
  access_token=sldfksgkkG78df78dgfjhnfknkn

The Token Endpoint returns response as a JSON object.

If the token is valid, the status code of response is 200. And the response contains the following fields:

The client must ensure that client_id matches exactly the identifier that the client received after registration.

An example of such response is shown below:

{ 
  "client_name": "My App", 
  "client_id": "45f4OJJdf", 
  "expires_in": 3602, 
  "scope": "profile send_orders", 
}

If validation fails for any reason - the token is expired, invalidated etc. - the status code of the response is 400.

An example of error response is shown below:

{ 
  "error": "invalid_request", 
}

5. Revoking the Token

Sometimes the client may need to revoke its access token. For example, when the client application needs to be deactivated. Health Gorilla provides service that allows clients to invalidate any access tokens or refresh tokens.

Health Gorilla OAuth 2.0 Revoke endpoint is:

https://api.healthgorilla.com/oauth/cancel

To revoke the token, an application should call the Revoke endpoint and pass the token in the token parameter. You can pass an access token or a refresh token. If the client makes the request and passes an access token, then a corresponding refresh token will also be invalidated.

Below you can find an example of such request:

https://api.healthgorilla.com/oauth/cancel?
  token=sldfksgkkG78df78dgfjhnfknkn

The Revoke Endpoint returns the response with 200 status code. Or the error HTTP response if any errors had occurred.

6. Accessing Protected Resources

The client accesses Health Gorilla API by presenting the access token in the request.

Access Token can be passed in two ways:

https://api.healthgorilla.com/result?
  access_token=sldfksgkkG78dsdff787&
  id=jdkfjsdjfkjksdfgjk767676f

GET /result HTTP/1.1 
Authorization: Bearer sldfksgkkG78dsdff787 
Host: api.healthgorilla.com

If the specified access token is not accepted, the endpoint rejects the request and returns an error to the client. Below you can find some common errors that the server may return. If the access token is expired, then the status code of the response is 401, and the result looks like the following:

HTTP/1.1 401 Unauthorized
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=435311D972BC5C1896C; Path=/; HttpOnly
WWW-Authenticate: Bearer realm="PatientServiceServlet",error="expired_token"
Content-Length: 0
Date: Tue, 17 Mar 2015 14:33:16 GMT

If the access token isn’t valid (it was never issued or was invalidated) then the status code of the response is 401 and the result looks like the following:

HTTP/1.1 401 Unauthorized
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=435311D972BC5C1896C; Path=/; HttpOnly
WWW-Authenticate: Bearer realm="PatientServiceServlet",error="invalid_token"
Content-Length: 0
Date: Tue, 17 Mar 2015 14:33:16 GMT

If the access token does not have the requested access rights, then the status code of the response is 403, and the result looks like the following:

HTTP/1.1 403 Forbidden
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=435311D972BC5C1896C; Path=/; HttpOnly
WWW-Authenticate: Bearer realm="PatientServiceServlet",error="insufficient_scope"
Content-Length: 0
Date: Tue, 17 Mar 2015 14:33:16 GMT

7. Retrieve User Info

Health Gorilla provides an API that can be used to retrieve some info about the logged user.

Health Gorilla OAuth 2.0 User Info endpoint is:

https://api.healthgorilla.com/oauth/userinfo

The application should make the GET request to the endpoint and pass the desired access token in the access_token parameter.

Below you can find an example of such a request:

https://api.healthgorilla.com/oauth/userinfo?
  access_token=sldfksgkkG78df78dgfjhnfknkn

The Token Endpoint returns response as JSON object (Content-Type: application/json).

List of available attributes:

Below you can find Organization attributes.

Below you can find Address attributes.

An example of such response is shown below:

{
    "uid": "e82806f23a131e02737779c1a9f7e365",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Gorilla",
    "degree": "Ph. D. Psychology",
    "fullName": "John Gorilla Doe, Ph. D. Psychology",
    "locale": "en_US",
    "administrativeRole": "Provider",
    "npi": "1033100045",
    "email": "[email protected]",
    "emailVerified": true,
    "mobilePhone": "(xxx) xxx-xxxx",
    "mobilePhoneVerified": false,
    "organization": {
        "name": "Dr. John M Doe, MD Practice",
        "phone": "(xxx) xxx-xxxx",
        "fax": "(xxx) xxx-xxxx",
        "faxVerified": false,
        "address": {
            "address1": "525 South Dr",
            "address2": " #115",
            "city": "Mountain View",
            "state": "CA",
            "zip": "94040",
            "country": "USA"
        }
    }
}

8. REST API Version

A particular REST API version can be requested when issuing an access token.
Include the following parameter into the HTTP request:

This is an optional parameter; if missed then the default predefined version is used.

You can find the associated API version in the response.

{ 
  "access_token": "sldfksgkkG78df78dgfjhnfknkn", 
  "expires_in": 3600, 
  "token_type": "Bearer",
  "refresh_token": "HKj87975vlJjkjhfH766",
  "scope": "place_orders",
  "hg_rest_api_version": "10-01-2019"
}

If the specified version is not available, then the request fails with error:

{ 
  "error": "unsupported_api_version", 
  "error_description": "The supplied Rest API version is not supported.", 
}