--- url: https://docs.codefox.ai/how-it-works/flows.md --- # Key flows, end to end This page traces four things Foxden does every day through the parts that do them, so you can see who checks what, and what happens when a part is missing or refuses. All four assume the apps are connected to Foxden Admin. For the parts themselves, see [The parts of Foxden](/how-it-works/big-picture). ## A person signs in to an app Signing in uses the OpenID Connect pattern with PKCE: Admin proves who the person is, and the app makes its own session from that proof. 1. The person opens an app, Fennec for example, and selects **Continue with** followed by your company's name (or **Continue with single sign-on** when no name is set). Some apps start this step by themselves. 2. Fennec makes a one-time secret and keeps it in a short-lived, httpOnly cookie. Only a hash of it travels in the browser. Fennec sends the browser to Admin's `/api/authorize` with that hash, a random `state`, its own name and its callback address. 3. Admin checks, in this order: * that the app is one it knows and the callback address is the one registered for it. If not, Admin stops there and never sends the browser on to an unchecked address; * that the request uses PKCE with SHA-256; * that the person is signed in to Admin. If not, Admin shows its own sign-in (Google, Microsoft or an email link, whichever the Owner turned on) and comes back here afterwards. When only Google or only Microsoft is turned on and there is no email link, Admin goes straight to it; * that the person holds a live grant for this app, read from Admin's database. 4. Admin sends the browser back to Fennec with a code that works once, for 60 seconds. 5. Fennec checks that `state` matches its cookie, then redeems the code at Admin's `/api/token` with the one-time secret from its cookie. Admin checks the grant again and answers with a signed assertion: Ed25519, valid for at most 120 seconds, naming the person, their level in Fennec and their grants. Fennec checks the signature against the keys Admin publishes, and refuses an assertion it has seen before. 6. Fennec finds the person in its own users table (by the account Admin linked earlier, then by email address), or creates them. A person whose account in Fennec is switched off is refused here, whatever Admin says. 7. Fennec tells Admin which of its own accounts this is, so later changes to the person's access reach the right account, and reads the access feed at once. 8. Fennec makes its own session, valid for 30 days. After that, Fennec never asks Admin about this person during a request. When an Owner removes someone's access, a new sign-in is refused at once, because Admin checks the grant at step 3. A session that is already open is checked against Admin's access feed, which the app reads about once a minute, in apps set to enforce it (`ACCESS_ENFORCEMENT=enforce`); see [Identity and access](/how-it-works/identity-and-access). If something fails, the person lands on the app's sign-in page with one of four reasons: Admin is not set up for this app, Admin refused (no grant), the account is switched off, or something else failed. See [Choose how people sign in](/run-your-company/sign-in). ## An AI assistant calls a tool 1. A person connects their assistant (Claude, Cursor and others) to Admin's gateway and approves it in their browser. The assistant gets a key for that person. See [Connect your AI assistant](/connect/ai-assistant). 2. The assistant sends a call, for example `fennec_list_deals`, to Admin's `/api/suite/mcp`. Admin checks the key before it reads anything else, and refuses a request larger than 1 MB (a few tools that carry files may send more). 3. Admin works out which apps this person reaches: an app appears only when the person holds a live grant for it, has an account there, and the app's address is known. An app they cannot use does not appear at all. 4. For the call, Admin makes a token for that one app, signed with the same keys as sign-in but of a different kind, so it can never start a session. It works once, for at most 60 seconds. Admin sends the call and the token to Fennec's own MCP server. 5. Fennec checks the token against Admin's published keys without calling Admin, finds the person, and runs the tool with that person's own level in Fennec. The gateway holds no powers of its own: an assistant can do exactly what its person can do in each app, and nothing more. 6. Fennec records the call in its own log and sends a copy to Admin, which shows it under **Workspace** › **Assistants**. Fennec also reads the Owner's rules from Admin every minute: a paused person, connection or tool, or a daily limit, is refused within a minute. Whether an assistant asks its person before it deletes, sends or spends is the **Asking before acting** setting. See [Ask before acting](/connect/ask-before-acting) and [The AI gateway](/connect/gateway). ## An app saves a file into Library Corsac storing the sealed copy of a signed document is a typical case. Fennec, Pampas, Culpeo and Admin work the same way. 1. Corsac asks its object store for a place to write. The store looks for the link between Corsac and Library: the secret for `files:corsac` (derived from the box key, or set by hand) and Library's address. With no link, Corsac writes to its own folder and the flow ends here. 2. Corsac sends the bytes to Library's `/api/suite/objects/` with four headers: its name, the time, the SHA-256 of the bytes, and a signature over the method, the path, the time and that hash, made with Corsac's own link secret. 3. Library picks Corsac's secret by the name in the header, checks the signature, and refuses a request more than five minutes old. Because the key is checked against the app that signed, Corsac can reach only Corsac's files. 4. Library stores the bytes against the hash Corsac signed and refuses them if they hash to anything else. Bytes it already holds are kept once. 5. Library names the bytes under Corsac's key. A key is written once: writing the same key again is refused, so a file is never replaced, only added. Reading streams the bytes back the same way. Deleting removes the name; Library's sweeper removes the bytes after the retention period (35 days unless you change it), so a database snapshot that still names them can be restored. See [Library as the file store](/how-it-works/file-store). ## An update rolls through the updater 1. An Owner selects **Update** on **Server** › **Products** in Admin and confirms. (`foxden update` on the server, and automatic updates, start the same sequence at step 3.) 2. Admin turns the click into a named operation, signs it, and sends it to the control service over a socket on the server. The control service refuses a request whose time is more than a minute off or that it has seen before, then runs `foxden update` for that app as a job and writes a line to the server's own log. Admin's activity log records who asked and how the job ended. 3. `foxden` sends a signed request to the app's updater. The updater writes each step to its journal before it acts, then: * checks there is enough free disk, when a floor is set; * pulls the new build; * for Arctic, waits until no notetaker is in a meeting; * takes a snapshot of the app's database; * starts the new build (each app migrates its own database as it starts); * waits for the app's health check to report the new version. 4. If the new version reports in, the updater records it in the app's settings file and the update is done. 5. If it does not, the updater stops the app, puts the database snapshot back, and starts the previous build. The person who asked sees that the previous version was put back. If putting the previous version back also fails, the updater keeps the snapshot as a recovery file and stops automatic updates for that app until an operator runs an update. See [Update Foxden](/self-host/update). ## Related * [Identity and access](/how-it-works/identity-and-access) * [Security and trust](/how-it-works/trust)