Skip to Content
Recall

Auth

Users, passkeys, invites, roles, API keys, sessions and the protections around them.

Recall has two ways in. People sign in to the dashboard at /app with a username and password or a passkey. Agents call /v1 and /mcp with an API key. Sign-in runs at /api/auth/*. It started on Better Auth; the Go server keeps its tables, password hashes and passkeys, so accounts carried over unchanged.

Users

  • A user signs in with a username and password. There's no email login and Recall sends no email.
  • Usernames are 3 to 32 characters: letters, numbers, dots and _. They're matched without regard to case, and the casing you typed is kept for display. A username never changes once created.
  • Passwords are 12 to 256 characters. New passwords are hashed with scrypt (Better Auth's format). The older pbkdf2$sha256$... format from ADMIN_PASSWORD_HASH still verifies.
  • Every user has an email in the database (Better Auth required one), so each one gets a placeholder <username>@users.recall.invalid. The .invalid domain is reserved and can never receive mail. The UI never shows it.
  • Users are created three ways only: by the admin CLI, by the first-boot bootstrap from ADMIN_PASSWORD_HASH, or by accepting an invite.
  • A signed-in user changes their password and manages passkeys in Settings, Account.

Passkeys

After signing in with a password, a user can add a passkey in Settings, Account, and then use "Sign in with a passkey" on the login page.

  • The relying party id (rpID) is the hostname of RECALL_URL (recall.zakiego.com in production), unless PASSKEY_RP_ID overrides it.
  • The WebAuthn origin is the origin of RECALL_URL.
  • Passkeys are bound to that hostname. Because the dashboard moved under /app on the same host and /api/auth stayed at the root, existing passkeys kept working.
  • A user can list and remove their own passkeys.

Invites

Owners and admins invite people from Settings, Members.

Create a link. Pick a role and copy the link, https://recall.zakiego.com/app/invite/<token>. It's shown once, like an API key. Only the token's sha256 hash is stored.

Send it. It's good for 7 days and works once.

The invitee opens it. Someone who isn't signed in picks a username and password. The account, the membership and a session are created in one step. Someone who is already signed in just joins, and the workspace becomes their active one.

Rules:

  • Single use: the invite is claimed and the membership written in one transaction, so two people can't use the same link.
  • Only owners can create owner invites. Admins can invite admins and members.
  • A link only works while its creator could still create it. Removing the creator from the workspace revokes their pending links. Demoting them revokes the links at roles they can no longer hand out. Acceptance checks the creator's current role again.
  • Owners and admins can revoke a pending link from Settings, Members.
  • An invalid link says so plainly: not valid, already used, revoked or expired.

Roles

Each membership has one role per workspace.

Actionowneradminmember
Read, search, add, edit and delete memoriesyesyesyes
See API keysyesyesyes
Create and revoke API keysyesyesno
Invite, change roles, remove membersyesyes (not owners)no
Leave the workspaceyes (not the last owner)yesyes
Create a new workspace (and own it)yesyesyes
  • Only owners make, change or remove owners.
  • A workspace always keeps at least one owner. The last owner can't leave or be demoted until someone else is an owner.
  • Removing a member also revokes the API keys they created in that workspace.
  • Workspaces can't be deleted.
  • Roles are read from the database on every dashboard call, so a change takes effect right away.

API keys

  • A key looks like rcl_ followed by 32 random characters.
  • It belongs to one workspace and only ever sees that workspace's data.
  • It's shown once, when created. Recall stores only its sha256 hash and the first 10 characters (for display).
  • Owners and admins create and revoke keys in Settings, API keys. Every member can see the list: name, prefix, who created it, when it was created and last used, and whether it's revoked.
  • An operator with access to the server can also create, list and revoke keys with the admin CLI.
  • Send it as Authorization: Bearer rcl_... (or X-API-Key: rcl_...). A revoked key stops working on the next request.
  • last used is updated at most once a minute per key.

Sessions and cookies

  • The session cookie is recall_session: HttpOnly, SameSite=Lax, and Secure whenever RECALL_URL is https. It holds a random token; the database stores only its SHA-256 hash.
  • Lax rather than Strict, so an invite link opened from a chat app still sees an existing session. Lax cookies are never sent on cross-site POSTs.
  • Sessions last 7 days and are refreshed once a day while in use.
  • SESSION_SECRET (32 or more characters) must be set. Without it the login page says the server isn't configured.
  • A new session lands in the user's first workspace. The workspace switcher changes it.

Origin and CSRF protection

  • Recall refuses every write to /api/auth whose Origin isn't RECALL_URL's origin, or whose Sec-Fetch-Site is cross-site, including sign-in (so there's no login CSRF). Those get 403 with INVALID_ORIGIN.
  • Dashboard calls that change anything refuse Sec-Fetch-Site: cross-site and a mismatched Origin.
  • The organization endpoints Better Auth had aren't reachable (404). Workspace, role and invite changes go through Recall's own rules instead.

Rate limits

All limits are in memory, per client IP (the CF-Connecting-IP header, then X-Forwarded-For, then X-Real-IP), in 60-second windows.

WhatLimit
Username sign-in5 per minute
Passkey sign-in (verify)5 per minute
Passkey sign-in (get options)10 per minute
Password change5 per minute
Everything else under /api/auth100 per minute
Invite lookup and acceptance10 per minute

The REST API and MCP have no rate limits.

On this page