Komodo Health Authentication

generated: '2026-08-15'
method: searched
source: >-
  https://docs.komodohealth.com/guides-tutorials/guides/2-authentication and —
  new on 2026-08-15 — the authorization server's own discovery documents at
  https://auth.komodohealth.com/.well-known/openid-configuration and
  /.well-known/oauth-authorization-server, saved verbatim under well-known/.
description: >-
  How callers authenticate to the Komodo Health platform. Komodo supports two
  mutually exclusive modes: interactive web login (OAuth 2.0 Device
  Authorization Flow, yielding a JWT) and machine-to-machine service-principal
  credentials (client_id / client_secret). Every call is scoped to a Komodo
  account, each of which maps to a dedicated Komodo-managed Snowflake warehouse.

  UPGRADED 2026-08-15: the 2026-07-19 round could only document these schemes
  from prose because Komodo publishes no OpenAPI. The Kong gateway at
  api.komodohealth.com answers every anonymous request with
  `WWW-Authenticate: Bearer realm="auth.komodohealth.com", error="invalid_token"`,
  and that authorization server publishes a full anonymous OIDC discovery
  document. The endpoints, grants, PKCE methods, signing algorithms and token
  endpoint auth methods below are now machine-read from the provider rather than
  inferred, and they corroborate the documented flows exactly (the device
  authorization endpoint confirms `komodo login`; client_credentials confirms
  service principals).
docs: https://docs.komodohealth.com/guides-tutorials/guides/2-authentication

authorization_server:
  issuer: https://auth.komodohealth.com/
  discovery:
    openid_configuration: https://auth.komodohealth.com/.well-known/openid-configuration
    oauth_authorization_server: https://auth.komodohealth.com/.well-known/oauth-authorization-server
    status: 200
    probed: '2026-08-15'
    files:
      - well-known/komodo-health-openid-configuration.json
      - well-known/komodo-health-oauth-authorization-server.json
      - well-known/komodo-health-jwks.json
  backed_by: Auth0 (auth0.com grant-type extensions present in grant_types_supported)
  ownership_note: >-
    auth.komodohealth.com is a Komodo-owned hostname and the issuer claim is
    https://auth.komodohealth.com/, so this authorization server belongs to
    Komodo Health even though the underlying identity platform is Auth0.
  endpoints:
    authorization: https://auth.komodohealth.com/authorize
    token: https://auth.komodohealth.com/oauth/token
    device_authorization: https://auth.komodohealth.com/oauth/device/code
    userinfo: https://auth.komodohealth.com/userinfo
    jwks: https://auth.komodohealth.com/.well-known/jwks.json
    revocation: https://auth.komodohealth.com/oauth/revoke
    registration: https://auth.komodohealth.com/oidc/register
    mfa_challenge: https://auth.komodohealth.com/mfa/challenge
    backchannel_authentication: https://auth.komodohealth.com/bc-authorize
    global_token_revocation: https://auth.komodohealth.com/oauth/global-token-revocation/connection/{connectionName}
  grant_types_supported:
    - client_credentials
    - authorization_code
    - refresh_token
    - password
    - implicit
    - urn:ietf:params:oauth:grant-type:device_code
    - urn:ietf:params:oauth:grant-type:token-exchange
    - urn:ietf:params:oauth:grant-type:jwt-bearer
    - http://auth0.com/oauth/grant-type/password-realm
    - http://auth0.com/oauth/grant-type/passwordless/otp
    - http://auth0.com/oauth/grant-type/mfa-oob
    - http://auth0.com/oauth/grant-type/mfa-otp
    - http://auth0.com/oauth/grant-type/mfa-recovery-code
  code_challenge_methods_supported: [S256, plain]
  token_endpoint_auth_methods_supported: [client_secret_basic, client_secret_post, private_key_jwt, none]
  id_token_signing_alg_values_supported: [HS256, RS256, PS256]
  dpop_signing_alg_values_supported: [ES256]
  subject_types_supported: [public]
  backchannel_logout_supported: true
  scopes_supported_detail: scopes/komodo-health-scopes.yml

schemes:
  - id: web_login
    type: oauth2
    flow: device_authorization
    rfc: RFC 8628
    description: >-
      Browser-based OAuth flow for interactive users. Started with `komodo
      login`; opens the browser, then persists the JWT and refresh token to the
      [default] profile in ~/.komodo/credentials. Intended for individual,
      manual use.
    token_type: JWT
    token_command: komodo jwt
    persisted: true
    persisted_to: ~/.komodo/credentials
    note: >-
      If no credentials are found the SDK triggers a web login automatically,
      but those credentials are in-memory only and are not written to disk.
  - id: service_principal
    type: oauth2
    flow: client_credentials
    description: >-
      Machine-to-machine authentication for automation, CI/CD and services.
      Service principals are created with `komodo service-principal create`,
      which returns a client_id and client_secret. No user interaction required.
    credentials: [client_id, client_secret]
    requires: account_id (or a named profile that carries it)
    management_commands:
      - komodo service-principal create --name "<name>" --description "<desc>"
      - komodo service-principal list
      - komodo service-principal delete <SERVICE_PRINCIPAL_ID>
  - id: explicit_jwt
    type: http
    scheme: bearer
    description: >-
      A JWT obtained from `komodo jwt` may be passed directly into the SDK
      alongside an account_id. In-memory only.

account_scoping:
  required: true
  description: >-
    A Komodo account is the organizational entity on the platform. Each account
    has its own data subscriptions and a dedicated Komodo-managed Snowflake
    warehouse. Every query and API operation is scoped to the selected account,
    and data does not move between accounts.
  identifiers:
    account_id: UUID uniquely identifying the account
    account_slug: human-readable account name
  selection: komodo account set (interactive) / komodo account get / komodo account list

credentials_file:
  path: ~/.komodo/credentials
  format: INI-style named profiles
  override_env: KOMODO_CREDENTIALS_PATH
  profiles:
    default: >-
      Written by `komodo login` and `komodo account set`. Carries token,
      token_expiration, account_id and account_slug.
    named: >-
      User-created profiles carrying client_id, client_secret, account_id and
      account_slug. Named profiles support M2M credentials only, not JWTs.

rules:
  - Only one authentication method may be used at a time.
  - JWT and explicit M2M credentials both require an account_id parameter.
  - Profiles cannot be combined with account_id — the profile already carries it.
  - jwt and client_id/client_secret cannot be mixed.

environments:
  - {name: production, default: true, public: true}
  - {name: integration, public: false, requires: komodo-internal-tools plugin}
  - {name: development, public: false, requires: komodo-internal-tools plugin}

scopes:
  published: partial
  detail: scopes/komodo-health-scopes.yml
  note: >-
    UPGRADED 2026-08-15. The authorization server advertises 14 scopes in its
    discovery document, but every one of them is a standard OpenID Connect
    identity/claim scope (openid, profile, email, offline_access, name,
    given_name, family_name, nickname, picture, created_at, identities, phone,
    address, email_verified). Komodo advertises NO resource scopes for its own
    API and publishes no scopes/permissions reference page. Platform
    authorization is expressed as Komodo account membership plus RBAC/FGA
    grantable roles on Komodo Apps and secrets (see the App Builder sharing
    tools). Do not read the OIDC scope list as a Komodo permission model.