Signing in and roles

Local books need no sign-in. A server uses any OAuth 2.0 / OpenID Connect provider, configured by issuer URL and discovery. Nothing is specific to one provider.

Roles

Roles come from a configurable claim, mapped by role_map onto ledger-read, ledger-write and ledger-rewrite. A signed-in identity becomes a user in the database and is recorded on each revision they make.

Apps

The app signs in with Authorization Code and PKCE in your system browser, redirecting to a loopback port. It never sees your password. It learns the issuer and client from the server, so a device only needs the server’s address. The refresh token lives in the system keyring, never in settings. Settings → Account shows who is signed in and signs out.

Assistants

MCP clients sign in themselves. /mcp validates bearer tokens exactly as the API does and points clients at your issuer through protected resource metadata.

When the server is away

What was last loaded stays readable, writes are off, and the app retries with backoff. It never queues writes. Local books never go offline.

Permission denied or expired session

Distinguish an unreachable server, an expired login and an authenticated user without the required role. Reconnect or sign in when asked; if the operation is forbidden, have the host check the token claim and role_map. Turning authentication off is not a remedy for a broken remote login.

A browser web session persists sign-in and refresh state in browser storage, with lifetime controlled by the provider. The native shell uses native token handling; on Linux refresh tokens use Secret Service. Signing out of the application and ending a provider’s SSO session are separate concerns.

• Server configuration and operations
• Troubleshooting and warning reference