OAuth 2.0

Welcome to Health Gorilla's Developer Portal. Access API documentation for our suite of clinical data APIs.

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 and an access token for your organization.

📘

Transport Layer Security

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

Resources

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 our contact form at https://www.healthgorilla.com/#contact.

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

Property NameDescriptionExample
Available Callback URLsList of URLs that your client will be able to specify in redirect_uri property when making OAuth 2.0 requests. Mandatory.https://yoursite1.com,
https://yoursite2.com,
iosapp://hgcallback”
Default callback URLThe default callback URL used by Health Gorilla OAuth 2.0 Authorization Server when OAuth request does not contain the redirect_uri parameter (optional).https://yoursite.com/callback
Attribution LogoLogo that will be visible to the user during authorization."Monkey Logo"
Web Site URLThis is a unique entity that identifies your resources.https://<yoursite.com>

When the request is completed, you will receive the following:

Property NameDescriptionExample
Client IDYour unique client application identifier.qpgW44
Client SecretSecret. It is your password that your client application will use to authenticate with Health Gorilla Clinical Network.

Important! You must treat the Client Secret in accordance with your Health Gorilla License Agreement.
eeVk7vcq
ScopesAvailable scopes is a
comma-separated list of permissions that identifies Clinical Network APIs for your client application’s access. Only the API calls defined in Scopes will be enabled for your application.
place_orders, get_profile

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://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:

response_typecode or token A predefined OAuth 2.0 constant.
code for Authorization Code Grant flow
token for Implicit Grant flow
client_idThe client identifierIdentifies the client that is making the request. This is the unique Client ID that you got after registration.
redirect_uriThe callback URLDefines the destination where to send response to.

If specified, then it should exactly match one of the callback URLs that you provided during registration.

If not specified, then the default callback URL will be used to respond.
scopeA list of space-delimited permissions that the client is requestingDefines the access rights to gain. Your application can request only scope that the client got after registration.

If empty, then the default scope is requested.
stateAny stringA value used by the client to maintain state between the request and callback.
Recommended to prevent XSRF attacks.

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.
  • Only five active OAuth tokens are allowed per client. If a new token is issued over the limit, then an oldest one is be revoked silently.

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:

2.1.1. Issue JWT

JWT token must contain the following claims:

ClaimValuesDescription
issAn unique identifier for the entity that issued the JWTMust match to a client URL which you sent to Health Gorilla during registration.
audhttps://www.healthgorilla.com/oauth/tokenHealth Gorilla OAuth 2.0 token endpoint.
subThe ID of the user that should be authenticated by JWTHealth Gorilla support will provide you this value.
exp‘expiration time’ claim that limits the time window during which the JWT can be used
nbf‘not before’ claim that identifies the time before which the token MUST NOT be accepted for processing
iat‘issued at’ claim that identifies the time at which the JWT was issued

JWT token must contain the following header parameters:

ParameterValues
typJWT

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:

ParameterDescription
grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer.
assertionJWT
client_idThe client ID obtained during registration.
scopeA list of space-delimited permissions that the client is requesting.

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: www.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.1.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:

ParameterValuesDescription
response_typecodeA predefined constant

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

Below you can find an example of the request:

https://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:

ParameterDescription
grant_typeauthorization_code
redirect_uriThe callback URl that was specified in the original request
client_idThe client ID obtained during registration.
client_secretThe client secret obtained during registration.
codeThe authorization code to exchange.

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: www.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:

FieldDescription
access_tokenThe access token issued by the authorization server.
refresh_tokenThe refresh token, which can be used to obtain new access tokens using the same authorization grant.
expires_inThe lifetime in seconds of the access token.
token_typeBearer.
scopeThe access rights that were granted and bound to the given access token.

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:

FieldDescription
errorError code.
error_descriptionAdditional information (optional).

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:

ParameterValuesDescription
response_typetoken A predefined constant.
Common authorization parameters......

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://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:

FieldDescription
access_tokenThe access token issued by the authorization server.
expires_inThe lifetime in seconds of the access token.
token_typeBearer.
scopeThe access rights that were granted and bound to the given access token.
stateThe exact value received from the client.

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:

ParameterValuesDescription
hg_user_first_nameFirst nameUser first name, if known.
hg_user_last_nameLast nameUser last name, if known.
hg_user_dobDate of birthUser date of birth, if known.
Format: YYYYMMDD
hg_user_emailEmail addressUser email, if known.

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://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:

ParameterDescription
grant_typerefresh_token
client_idThe client ID obtained during registration.
client_secretThe client secret obtained during registration.
refresh_tokenThe secure refresh token issued by the authorization server.

Below you can find an example of that request:

POST /oauth/token HTTP/1.1 
Host: www.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:

FieldDescription
access_tokenThe new access token issued by the authorization server.
refresh_tokenThe new refresh token, which can be used to obtain new access tokens using the same authorization grant.
expires_inThe lifetime in seconds of the access token.
token_typeBearer
scopeThe access rights that were granted and bound to the given access token.

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:

FieldDescription
errorAn error code.
error_descriptionAdditional information (optional).

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://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://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:

ValueDescription
client_nameThe name of the client that is identified as an
owner of the token.
client_idThe ID of the client that is identified as an owner of the token.
expires_inThe lifetime in seconds of the access token.
scopeThe list of granted scopes, space-delimited.

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://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://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://healthgorilla.com/result?
  access_token=sldfksgkkG78dsdff787&
  id=jdkfjsdjfkjksdfgjk767676f
GET /result HTTP/1.1 
Authorization: Bearer sldfksgkkG78dsdff787 
Host: 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://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://www.healthgorilla.com/oauth/userinfo?
  access_token=sldfksgkkG78df78dgfjhnfknkn

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

List of available attributes:

ValueDescription
uidThe ID of the user in Health Gorilla.
firstNameThe given name.
lastNameThe surname.
middleNameThe middle name.
degreeThe degree.
fullNameThe full name.
localeThe preferred locale (en_US or es).
administrativeRoleThe administrative role (Provider, Nurse, Staff, Office Manager, Billing Staff).
npiThe NPI number.
emailThe email.
emailVerifiedTrue if the specified email is verified.
mobilePhonehe mobile phone.
mobilePhoneVerifiedTrue if the specified mobile phone is verified.
dobThe date of birth.
genderThe gender.
organizationThe organization

Below you can find Organization attributes.

ValueDescription
nameThe name.
phoneThe phone number.
faxThe fax number.
faxVerifiedTrue if the specified fax is verified.
addressThe address.

Below you can find Address attributes.

ValueDescription
address1The address row.
address2The address row.
cityThe city.
stateThe state.
zipThe postal code.
countryThe country code (A3C).

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:

ParameterValueDescription
hg_rest_api_versionConstantThe REST API version to use within the OAuth session.
Example: 10-01-2019

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.", 
}