Metriport Authentication

generated: '2026-08-14'
method: searched
docs: https://docs.metriport.com/medical-api/getting-started/api-keys
source: >-
  https://docs.metriport.com/medical-api/getting-started/api-keys,
  /medical-api/more-info/sso, /medical-api/getting-started/embedding,
  /medical-api/getting-started/webhooks; scheme confirmed against the
  securitySchemes in openapi/*.yml.
summary:
  types:
  - apiKey
  api_key_in:
  - header
schemes:
- name: ApiKeyAuth
  type: apiKey
  in: header
  parameter: x-api-key
  sources:
  - openapi/metriport-consolidated-api-openapi.yml
  - openapi/metriport-devices-data-api-openapi.yml
  - openapi/metriport-document-api-openapi.yml
  - openapi/metriport-facility-api-openapi.yml
  - openapi/metriport-patient-api-openapi.yml
  - openapi/metriport-settings-api-openapi.yml
  - openapi/metriport-user-api-openapi.yml
  - https://docs.metriport.com/medical-api/getting-started/api-keys
  detail: >-
    A single static key grants full access to the account, including destructive
    operations. There are no scopes, no restricted or read-only keys, and no
    per-facility scoping. Metriport's own guidance is to treat the key like an
    account password and use it only from backend services.
  key_management:
    issued_from: https://dash.metriport.com/developers
    max_active_keys: 2
    rotation: >-
      Both keys are equally privileged and interchangeable, so rotation is
      generate-new, roll-out, revoke-old with zero downtime.
    revocation: Immediate — revoking a key on the Developers page makes it inactive at once.
  environments:
  - name: production
    base_url: https://api.metriport.com
  - name: sandbox
    base_url: https://api.sandbox.metriport.com
    note: Minted separately after toggling Sandbox mode in the dashboard; not interchangeable with production keys.
  key_format:
    prefix: none published
    note: >-
      Metriport publishes no distinguishing key prefix for sandbox versus
      production. A client cannot tell which environment a key belongs to by
      inspecting it, and a leaked key has no scannable shape.
oauth2: false
oidc: false
mtls: false
adjacent_credentials:
- name: Embed token
  type: URL-borne bearer token
  parameter: access_token (query parameter on the embedded app URL)
  minted_by: POST /medical/v1/token/embed, server-side, using the API key
  max_lifetime_seconds: 36000
  purpose: Authorises the hosted embedded app (Patient View, Transitions of Care) in a browser.
  docs: https://docs.metriport.com/medical-api/getting-started/embedding
- name: Webhook key
  type: HMAC shared secret
  parameter: x-metriport-signature (on inbound requests FROM Metriport)
  algorithm: HMAC-SHA256 over the raw body
  purpose: Lets your endpoint verify that a webhook came from Metriport.
  rotation: Clear and re-set the webhook URL to regenerate.
  docs: https://docs.metriport.com/medical-api/getting-started/webhooks
- name: SAML / Enterprise SSO
  type: SAML 2.0
  purpose: >-
    Human sign-in to the Metriport dashboard only — NOT an API authentication
    method. Named IdP guides for Google, Okta, Azure, OneLogin, JumpCloud, Duo
    and Rippling; attribute mapping on email, first_name, last_name.
  docs: https://docs.metriport.com/medical-api/more-info/sso
gaps:
- No OAuth 2.0 or OIDC; no delegated or third-party authorisation flow.
- No scoped, restricted or read-only API keys — least privilege is not expressible.
- No mutual TLS.
- No key-prefix convention, so leaked keys cannot be pattern-detected by secret scanners.
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com