Umami Authentication

generated: '2026-08-13'
method: searched
source: https://docs.umami.is/docs/api/authentication + https://docs.umami.is/docs/cloud/api-key
docs:
  - https://docs.umami.is/docs/api/authentication
  - https://docs.umami.is/docs/cloud/api-key
  - https://docs.umami.is/docs/two-factor-authentication
provider: Umami
providerId: umami
description: >-
  Umami has two distinct authentication paths that share one wire format. Both
  send a bearer credential in the Authorization header, but they are obtained
  differently, live on different hosts, and are not interchangeable.
summary:
  types:
    - http
  schemes_count: 2
  oauth2: false
  openid_connect: false
  mtls: false
  note: >-
    No OAuth 2.0, no OpenID Connect, no scopes, no mTLS. There is nothing to
    delegate: a Umami credential is all-or-nothing for the account or user it
    belongs to. See scopes/ — no OAuthScopes artifact is emitted because there
    are no scopes to record.
schemes:
  - name: cloudApiKey
    type: http
    scheme: bearer
    surface: Umami Cloud
    host: https://api.umami.is/v1
    description: >-
      An API key generated in the Umami Cloud UI (Settings → API keys → Create
      key) and sent as `Authorization: Bearer <api-key>`. This is the only way
      to reach Umami Cloud programmatically.
    obtained_by: manual creation in the Umami Cloud dashboard
    programmatic_issuance: false
    rotation: >-
      Keys can be deleted from the API keys screen; deletion is irreversible. No
      documented expiry, no documented rotation API.
    plan_gated: true
    plan_note: >-
      API access is NOT available on the free Hobby plan. It starts at Pro
      ($20/month). This is an access-model fact, not just a pricing one.
    restrictions:
      - >-
        The following routes are NOT available to an API key, even a valid one:
        /me/password, /users, /users/*. User administration is UI-only on Cloud.
    regions:
      default: the region of the account that owns the key
      pinnable: true
      form: https://api.umami.is/v1/us | https://api.umami.is/v1/eu
    rate_limit: 50 calls per 15 seconds per key (see rate-limits/)
    docs: https://docs.umami.is/docs/cloud/api-key
    source: https://docs.umami.is/docs/cloud/api-key
  - name: selfHostedJwt
    type: http
    scheme: bearer
    bearerFormat: JWT
    surface: self-hosted Umami
    host: http://<your-umami-instance>/api
    description: >-
      A JWT obtained by POSTing username/password to /api/auth/login, then sent
      as `Authorization: Bearer <token>` on every subsequent call. Applies to
      self-hosted instances only — Umami Cloud does not use it.
    obtained_by: POST /api/auth/login
    verify: POST /api/auth/verify returns the token's user, or fails if expired.
    logout: POST /api/auth/logout
    expiry: not documented
    rotation: re-login
    docs: https://docs.umami.is/docs/api/authentication
    source: https://docs.umami.is/docs/api/authentication
unauthenticated_endpoints:
  - path: POST /api/send
    reason: >-
      Data collection. Requires no token but DOES require a valid User-Agent
      header or the request is not registered. Umami Cloud collection posts to
      gateway.umami.is as of 2026-06-06 (previously cloud.umami.is/api/send).
    source: https://docs.umami.is/docs/api/sending-stats
  - path: POST /api/batch
    reason: Batched collection; same rules as /api/send.
    source: https://docs.umami.is/docs/api/sending-stats
  - path: GET /api/websites/:websiteId/recorder
    reason: >-
      Recorder configuration read by the tracker to initialize session replay
      and heatmaps. Documented as publicly accessible with no authentication.
      Returns {"enabled": false} when the website does not exist or recording is
      off.
    source: https://docs.umami.is/docs/api/websites
  - path: /share/:shareId
    reason: >-
      Share URLs render a dashboard to anyone holding the link. shareId is set
      per website and can be revoked by setting it to null.
    source: https://docs.umami.is/docs/enable-share-url
account_security:
  two_factor:
    supported: true
    surface: application login (self-hosted and Cloud)
    enforcement: >-
      Can be enforced globally by an admin and per team; API routes exist at
      /api/2fa/* and /api/admin/2fa/global.
    docs: https://docs.umami.is/docs/two-factor-authentication
    note: TOTP protects interactive login. It does not gate API-key use.
  sso:
    supported: true
    protocol: SAML
    availability: Enterprise plan only
    source: https://umami.is/pricing
observed:
  - probe: GET https://api.umami.is/v1/websites (no credential)
    status: 400
    body: '{"error":{"message":"No API key specified.","code":"bad-request","status":400}}'
    date: '2026-08-13'
  - probe: GET https://api.umami.is/v1/websites (Authorization Bearer <invalid>)
    status: 401
    body: '{"error":{"message":"Invalid API key.","code":"unauthorized","status":401}}'
    date: '2026-08-13'
    note: >-
      Missing credential is answered 400, not 401 — worth knowing for client
      error handling, since most APIs return 401 for both.
prior_state: >-
  Superseded the 2026-07-11 derived profile, which recorded a single bearerAuth
  scheme from the scaffold OpenAPI and conflated the Cloud API key with the
  self-hosted JWT into one description.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com