OAuth 2.0 Authentication

Health Gorilla APIs use OAuth 2.0 for authentication and authorization. All protected endpoints require a valid bearer access token.

Base URL: https://api.healthgorilla.com

All endpoints require TLS 1.2 or higher.

Authorization Endpoint

GET /oauth/authorize

Initiates an OAuth 2.0 authorization request.

Endpoint: GET /oauth/authorize

Query Parameters

Parameter	Required	Description
`response_type`	Yes	`code` (Authorization Code) or `token` (Implicit)
`client_id`	Yes	Client identifier issued during registration
`redirect_uri`	Conditional	Must exactly match a registered callback URL
`scope`	Optional	Space-delimited list of requested scopes
`state`	Recommended	Opaque value used to prevent CSRF
`hg_user_first_name`	No	Optional extended parameter
`hg_user_last_name`	No	Optional extended parameter
`hg_user_dob`	No	Format: `YYYYMMDD`
`hg_user_email`	No	Optional extended parameter

Success Response

Redirect to redirect_uri with:

Authorization Code Grant

?code=<authorization_code>&state=<state>

Implicit Grant

#access_token=<token>&token_type=Bearer&expires_in=<seconds>&scope=<scope>&state=<state>

Error Responses

400 Bad Request (invalid client or invalid redirect URI)
Redirect with error, error_description, and state (if provided)

Token Endpoint

POST /oauth/token

Exchanges an authorization grant for an access token or refreshes an existing token.

Endpoint

POST /oauth/token

Successful responses return HTTP 200 OK with Content-Type: application/json.

Error responses return HTTP 400 Bad Request unless otherwise specified.

Supported Grant Types

Authorization Code

Parameter	Required
`grant_type=authorization_code`	Yes
`code`	Yes
`client_id`	Yes
`client_secret`	Yes
`redirect_uri`	Yes

The scope granted during token exchange is limited to the scopes approved during client registration and the original authorization request. Scope cannot be expanded during token exchange.

Refresh Token

Parameter	Required
`grant_type=refresh_token`	Yes
`refresh_token`	Yes
`client_id`	Yes
`client_secret`	Yes

JWT Bearer

Parameter	Required
`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`	Yes
`assertion`	Yes
`client_id`	Yes
`scope`	Optional

JWT assertions must be signed using HS256 (HMAC SHA-256) with the client secret and include required claims as defined in the OAuth JWT Bearer specification.

The aud claim must be set to https://api.healthgorilla.com/oauth/token.

If the scope parameter is omitted, the default scopes assigned to the client during registration are applied.

Successful Response

Field	Description
`access_token`	Bearer token used to access protected resources
`expires_in`	Token lifetime in seconds
`token_type`	Always `Bearer`
`refresh_token`	Present if issued
`scope`	Granted scopes
`hg_rest_api_version`	API version bound to this session (if specified)

Example:

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

Error Response

Field	Description
`error`	Error code
`error_description`	Additional information (optional)

Common error values:

invalid_grant
invalid_client
unsupported_grant_type
unsupported_api_version

Token Validation Endpoint

GET /oauth/info

Validates an access token.

Endpoint

GET /oauth/info?access_token=<token>

Successful responses return HTTP 200 OK with Content-Type: application/json.

Success Response (200 OK)

Field	Description
`client_name`	Name of client application
`client_id`	Client identifier
`expires_in`	Remaining token lifetime (seconds)
`scope`	Space-delimited granted scopes

If the token is invalid or expired, the endpoint returns 400 Bad Request.

Token Revocation Endpoint

GET /oauth/cancel

Revokes an access or refresh token.

Endpoint

GET /oauth/cancel?token=<token>

Returns 200 OK on success.

Successful revocation requests return HTTP 200 OK with no response body. If an access token is revoked, its associated refresh token is also invalidated.

User Info Endpoint

GET /oauth/userinfo

Returns information about the authenticated user.

Endpoint

GET /oauth/userinfo?access_token=<token>

Successful responses return HTTP 200 OK with Content-Type: application/json.

Response Fields

Field	Description
`uid`	Health Gorilla user identifier
`firstName`	Given name
`lastName`	Surname
`middleName`	Middle name
`degree`	Professional degree
`fullName`	Full formatted name
`locale`	Preferred locale
`administrativeRole`	Administrative role within tenant
`npi`	NPI (if applicable)
`email`	Email address
`emailVerified`	Boolean
`mobilePhone`	Mobile phone
`mobilePhoneVerified`	Boolean
`dob`	Date of birth
`gender`	Gender
`organization`	Organization object

Accessing Protected Resources

Access tokens must be sent using the Authorization header:

Authorization: Bearer <access_token>

If the token is:

Expired → 401 Unauthorized (expired_token)
Invalid → 401 Unauthorized (invalid_token)
Missing required scope → 403 Forbidden (insufficient_scope)

API Version Targeting

A specific REST API version may be requested during token issuance by including:

hg_rest_api_version=<version>

If omitted, the default API version is used.
If the requested version is unsupported, the token endpoint returns:

400 Bad Request
error=unsupported_api_version