Komodohealth Authentication

generated: '2026-07-19'
method: searched
source: https://docs.komodohealth.com/guides-tutorials/guides/2-authentication/
docs: https://docs.komodohealth.com/guides-tutorials/guides/2-authentication/
notes: >-
  Derived by SEARCH of the published authentication guide and SDK/CLI reference.
  Komodo Health publishes no public OpenAPI document
  (https://api.komodohealth.com/openapi.json returns 401), so the scheme set
  below is captured from documentation rather than from securitySchemes.
summary:
  types: [oauth2]
  oauth2_flows: [deviceCode, clientCredentials]
  token_format: JWT
  account_scoped: true
  api_key_in: []
schemes:
- name: WebLogin
  type: oauth2
  flow: deviceCode
  description: >-
    Browser-based OAuth 2.0 Device Authorization Flow for interactive users.
    Started with `komodo login`; stores a JWT plus refresh token. Triggered
    automatically by the SDK when no credentials are found (in that case the
    credentials live in memory only and are not persisted).
  credential: JWT bearer token
  persisted_to: ~/.komodo/credentials
  profile: '[default]'
  requires: [account_id]
  sources: [docs]
- name: ServicePrincipal
  type: oauth2
  flow: clientCredentials
  description: >-
    Machine-to-machine authentication using service-principal credentials for
    automation, CI/CD, and services. No user interaction required.
  credential: client_id + client_secret
  provisioning: uv run komodo service-principal create --name "my-service"
  persisted_to: ~/.komodo/credentials
  profile: named profile (e.g. [production], [development])
  requires: [account_id]
  sources: [docs]
scopes:
  documented: false
  note: >-
    Komodo publishes no OAuth scope/permission reference. Authorization is
    account-scoped (each account has an isolated, Komodo-managed Snowflake
    warehouse) with Snowflake roles applied inside it, plus RBAC/FGA app roles
    for the App Builder surface. No scopes/ artifact is emitted.
accounts:
  model: >-
    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.
    Accounts are isolated — data does not move between them.
  identifiers:
  - {name: account_id, format: UUID, example_shape: 8-4-4-4-12}
  - {name: account_slug, format: human-readable string}
  selection: uv run komodo account set
credentials_file:
  default_path: ~/.komodo/credentials
  format: INI-style named profiles
  override_env: KOMODO_CREDENTIALS_PATH
  tilde_expansion: true
  fields_default_profile: [token, token_expiration, account_id, account_slug]
  fields_m2m_profile: [client_id, client_secret, account_id, account_slug]
precedence:
- rank: 1
  description: Explicit credentials passed to the SDK function (jwt + account_id, client_id + client_secret + account_id, or profile)
- rank: 2
  description: '[default] profile from ~/.komodo/credentials (written by `komodo login`)'
- rank: 3
  description: Browser web-login flow triggered by the SDK (not persisted to disk)
constraints:
- Only one authentication method may be used at a time.
- JWT and explicit M2M credentials both require an account_id.
- A profile cannot be combined with account_id — the profile already contains it.
- jwt cannot be mixed with client_id / client_secret.
- Named profiles support M2M credentials only, not JWT tokens.
token_refresh:
  automatic: true
  note: The SDK refreshes JWTs automatically via the stored refresh token.
related:
  conventions: conventions/komodohealth-conventions.yml
  errors: errors/komodohealth-error-codes.yml