Health Gorilla OAuth Scopes

generated: '2026-08-14'
method: searched
source: https://api.healthgorilla.com/.well-known/smart-configuration
docs: https://developer.healthgorilla.com/docs/scopes-access-control
description: >-
  Health Gorilla's OAuth scope surface is published in two places: the SMART App
  Launch configuration served anonymously from the API host, which enumerates
  the scopes the authorization server supports, and the Scopes & Access Control
  guide, which describes how scopes are assigned and enforced. Scopes are fixed
  at client registration — a client may request only scopes assigned during
  onboarding, cannot self-assign, cannot expand scope during token exchange, and
  cannot expand scope on refresh. The OpenAPI in openapi/ declares only a bearer
  http scheme with no oauth2 flows, so none of this is derivable from the spec;
  every scope below comes from the provider's own discovery document or docs.
schemes:
- name: SMARTonFHIR
  type: oauth2
  source: well-known/health-gorilla-smart-configuration.json
  flows:
  - flow: authorizationCode
    authorizationUrl: https://www.healthgorilla.com/oauth/authorize
    tokenUrl: https://www.healthgorilla.com/oauth/token
  - flow: implicit
    authorizationUrl: https://www.healthgorilla.com/oauth/authorize
  - flow: clientCredentials
    tokenUrl: https://www.healthgorilla.com/oauth/token
  - flow: jwtBearer
    tokenUrl: https://www.healthgorilla.com/oauth/token
scopes:
- scope: user/*.*
  family: smart
  description: >-
    SMART user-level access. Grants the app the intersection of the client's
    registered scopes and the authenticated user's permissions within the tenant.
  flows: [authorizationCode, implicit]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: system/*.*
  family: smart
  description: >-
    SMART backend-services (system) access for server-to-server integrations
    with no interactive user.
  flows: [clientCredentials, jwtBearer]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: offline_access
  family: smart
  description: Requests a refresh token so the client can renew access without re-authorizing.
  flows: [authorizationCode]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: openid
  family: oidc
  description: Enables OpenID Connect single sign-on and issuance of an id_token.
  flows: [authorizationCode, implicit]
  sources: [well-known/health-gorilla-smart-configuration.json, well-known/health-gorilla-openid-configuration.json]
- scope: profile
  family: oidc
  description: Releases the user profile claims (name, given_name, family_name, birthdate, gender).
  flows: [authorizationCode, implicit]
  sources: [well-known/health-gorilla-smart-configuration.json, well-known/health-gorilla-openid-configuration.json]
- scope: fhirUser
  family: oidc
  description: Releases the fhirUser claim identifying the FHIR resource for the authenticated user.
  flows: [authorizationCode, implicit]
  sources: [well-known/health-gorilla-smart-configuration.json, well-known/health-gorilla-openid-configuration.json]
- scope: patient360
  family: health-gorilla
  description: >-
    Health Gorilla proprietary scope gating the Patient360 record-retrieval
    product ($p360-retrieve / $p360-search on DocumentReference and Patient).
  flows: [authorizationCode, clientCredentials]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: rls
  family: health-gorilla
  description: >-
    Health Gorilla proprietary scope for the Record Locator Service, which
    locates where a patient's records exist across the network before retrieval.
  flows: [authorizationCode, clientCredentials]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: nlp
  family: health-gorilla
  description: >-
    Health Gorilla proprietary scope for natural-language / OCR processing of
    retrieved clinical documents (see the DocumentReference $ocr operation).
  flows: [authorizationCode, clientCredentials]
  sources: [well-known/health-gorilla-smart-configuration.json]
- scope: create_users
  family: health-gorilla
  description: >-
    Permits provisioning of Health Gorilla users. Named in the Scopes & Access
    Control guide as an example of a per-integration scope assigned at
    registration; it is not advertised in the SMART configuration.
  flows: [authorizationCode, clientCredentials]
  sources: ['https://developer.healthgorilla.com/docs/scopes-access-control']
- scope: place_orders
  family: health-gorilla
  description: >-
    Permits submission of diagnostic (lab / radiology) orders. Appears as the
    granted scope in the token response example in the OAuth 2.0 Authentication
    reference; it is not advertised in the SMART configuration.
  flows: [authorizationCode, clientCredentials]
  sources: ['https://developer.healthgorilla.com/reference/oauth-20-authentication']
enforcement:
  assignment: >-
    Scopes are configured at registration and bound to a specific client_id.
    Additional API access requires a scope change requested through Health Gorilla.
  request_format: space-delimited list on the scope parameter
  default_behavior: >-
    If scope is omitted from the authorization request, the client's registered
    default scopes are applied.
  downscoping: The authorization server may issue a token with a subset of the requested scopes.
  expansion: >-
    Scope cannot be expanded during token exchange or refresh. For the
    authorization code grant, the granted scope cannot exceed the scope requested
    in the original authorization request.
  two_layer_model: >-
    OAuth scopes govern which APIs the client may call; user-level permissions
    govern what data and operations are permitted inside the tenant. Both must be
    satisfied. Scopes never grant access outside the token's tenant context.
  failures: [insufficient_scope, invalid_client, invalid_grant]
completeness:
  note: >-
    Health Gorilla does not publish an exhaustive scope reference. The SMART
    configuration lists nine supported scopes and the docs name two further
    per-integration scopes by example, stating explicitly that "the exact scopes
    available to a client are defined at registration time and vary by
    integration." No additional scopes were invented to fill the gap.
  advertised_in_discovery: 9
  named_in_docs_only: 2
x-evidence:
- {url: 'https://api.healthgorilla.com/.well-known/smart-configuration', http_status: 200, fetched: '2026-08-14'}
- {url: 'https://developer.healthgorilla.com/docs/scopes-access-control.md', http_status: 200, fetched: '2026-08-14'}
- {url: 'https://developer.healthgorilla.com/reference/oauth-20-authentication.md', http_status: 200, fetched: '2026-08-14'}