The Access Graph Behind a Shared Workspace
Open WebUI's access model answers a harder question than “Who is logged in?” It must decide whether a particular user may see or change a particular model, file, knowledge base, channel, chat, tool, note, calendar, or scheduled workflow. This chapter maps that decision from authentication through groups, resource grants, ownership, model inheritance, and indirect file relationships. The practical outcome is a way to locate the relevant permission boundary instead of assuming that one role check can secure the whole workspace.
The central idea is an access graph. A user is connected to groups. Groups contribute permissions. Resources are connected to owners and grants. Models can point to base models. Files can be attached to knowledge bases, models, channels, and chats. Tools, calendars, and automations can carry their own access conditions. A request succeeds only when the relationships on the path support the requested operation.
Authentication is only the first gate
Open WebUI can receive identity through a browser session, a bearer JWT, an API key, and selected OAuth or trusted-header arrangements. These mechanisms answer an identity question: which account is associated with this request? They do not, by themselves, answer whether the account is verified, whether it has an administrator role, or whether it may access the resource named in the request.
The distinction is visible in the user states. The application separates verified users from pending accounts and treats administrators as a distinct role. A valid token for a pending account is not equivalent to a verified user who may use the full workspace. An administrator check is a further decision, used for configuration and other privileged operations. If those layers are collapsed into “the token was valid,” later resource checks become difficult to reason about.
Session lifecycle matters as well. JWTs carry an identifier and an issue time. When Redis is configured, Open WebUI can revoke one token by its identifier, or reject tokens issued for a user before a stored revocation time. The latter is important after events such as a password change or an OAuth back-channel logout, when the system may not know every individual token that should stop working. Without Redis, the source notes that existing sessions can remain valid until expiry in some revocation situations. Redis is therefore part of the session invalidation boundary, not merely a performance cache.
API keys add another layer of scope. The key resolves to a user, but API-key use can be disabled globally, restricted by a user permission, and limited to configured endpoint paths. The path check is performed where the key is resolved so it applies regardless of how the key arrived. This matters because an API request may not have the same browser cookies, session callbacks, or user interface assumptions as an interactive chat. A credential mechanism should be evaluated together with the operations it is allowed to invoke.
Trusted identity headers have a similar dependency. They can help an upstream proxy or identity system associate a request with a user, but their safety depends on the deployment's proxy and header configuration. The code verifies a configured trusted email against the user resolved from a token when that mode is in use.