Caching & Authentication

Response caching

Reporting calls (stats, activeVisitors, pageviews, metrics) are cached using your application's default cache store. Keys are namespaced with config('oi-laravel-umami.cache.prefix') and include the website id, endpoint, and a hash of the query, so different date ranges and dimensions are cached independently.

Set the lifetime with cache.ttl (seconds) and bypass it per call with fresh: true. Management calls (websites/users CRUD) are never cached.

Token caching (self-hosted)

When authenticating with username/password, the bearer token returned by POST {base_url}/auth/login is cached for cache.token_ttl seconds under {prefix}:token. Subsequent requests reuse it until it expires, avoiding a login round-trip on every call. Umami Cloud (API key) skips this entirely.

Error handling

HTTP failures bubble up as Illuminate\Http\Client\RequestException (responses are ->throw()n). Misconfiguration — a missing website id, or missing credentials — raises InvalidArgumentException before any request is sent.