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
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
docs_pages:
- https://docs.umami.is/docs/api/authentication
- https://docs.umami.is/docs/cloud/api-key
- https://docs.umami.is/docs/two-factor-authentication