Komodo Health Authentication

generated: '2026-07-19'
method: searched
source: https://docs.komodohealth.com/guides-tutorials/guides/2-authentication
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.
  Derived from the published auth guide — Komodo does not publish an OpenAPI
  document, so these schemes are documented rather than machine-read.
docs: https://docs.komodohealth.com/guides-tutorials/guides/2-authentication

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: false
  note: >-
    Komodo does not publish an OAuth scope or permission reference. App-level
    authorization is expressed as grantable roles on Komodo Apps (see the
    App Builder sharing tools) and RBAC/FGA on app and secret resources.