Documentation

FoxAuth is built on OAuth-server.ts, a source-available OAuth 2.1 and OpenID Connect authorization server. You can run it yourself, or use it free on FoxAuth Cloud. This documentation covers three jobs: getting a server running, connecting an application to it, and operating it once real users depend on it. Pick the one you are doing now.

Getting it running

Start with Run with Docker Compose. One command starts MongoDB, provisions the schema and serves the authorization server, and it is probably the fastest way to see a working instance. If you would rather work against the source, Run from source clones the repository and starts it with Bun.

Either way the next step is Create the first administrator: a fresh database has no accounts, and the one-time setup screen is how the first one is made. Turn on the second factor there before anything else.

To skip running a server, create a free account on FoxAuth Cloud, our instance at auth.foxauth.dev. You get a personal team, and up to two projects on the Free plan. The Get started pages assume a server at http://localhost:3000: on the cloud, use your project’s issuer, shown on its Overview, in its place. The Free plan offers sign-in through Google, Microsoft, Apple and GitHub only.

Connecting an application

An application talks to the server as an OAuth client, and a client has to exist before it can ask for a token. Register your first client covers the pieces that trip people up: the difference between a public and a confidential client, why redirect URIs are matched exactly and never by pattern, and which project a client signs people in from.

Then Get your first token walks the Authorization Code flow with PKCE end to end using curl, from the code challenge to a decoded ID token and a UserInfo call. PKCE is mandatory for every client, not only public ones. That is OAuth 2.1, and in our experience it is the most common surprise for anyone arriving from an OAuth 2.0 server.

If the application you are connecting is an MCP server, it is not an OAuth client but a protected resource, and the shape is different enough to have its own page: Protect your MCP server with OAuth declares it here, publishes the two things an MCP server has to publish, validates a token, and shows both a refusal and a success.

Running it in production

Deploy covers the targets people actually use: Fly.io, Kubernetes, Docker Compose on a single host. The database is a choice of two, MongoDB or PostgreSQL, and the connection string you set is what picks between them. Whichever you choose, Behind a reverse proxy matters. The issuer URL must be an https:// address and must match what clients were configured with. A proxy that rewrites headers without being told to is the usual cause of tokens that validate locally and fail in production.

Read Upgrading before you move between versions. Since 1.0.0 the HTTP surface and the admin API change incompatibly only in a major release; the changelog says what moved, and the setup script has to be re-run afterwards so new collections and indexes exist, followed by bun run db:migrate for anything a release has to reshape.

Running it for real users

Once people sign in through it, the work moves to the console. Connect an upstream identity provider lets a project’s users sign in through Google, Microsoft, Apple, GitHub or any OpenID provider, and decides which accounts such a sign-in may create or link. With that in place, Provision users from Entra ID or Okta hands the project’s users and groups to the directory over SCIM, and Sign-out from upstream providers lets a sign-out there end the sessions here.

Teams and project ownership covers the administrator teams that own projects and moving a project between them. Project addresses compares the three addresses a project can have, a path, a subdomain or a hostname of its own, and what the subdomain form needs from the operator. Groups and the groups claim covers the groups of end users a relying party reads in place of roles. End a user’s access compares deactivation, the lock, signing out everywhere and deletion, and names the one token none of them can recall. Rotate signing keys rotates the instance’s and each project’s keys in one step without a restart, and revokes a compromised key at once. Plans and Free-tier limits is for a public instance where anyone may register as an administrator: it limits what each team may create, and pauses new sign-ups at a project’s monthly active-user cap.

Deciding whether to trust it

An authorization server is the front door of everything behind it. Before you put one in front of real users you are entitled to ask what it defends against and how anyone knows. The threat model answers the first question: the assets, the attackers, and for each threat the control in the code and the test that holds it, along with the limitations that are true today. Security assurance answers the second: the scanning that runs on every push and every week, where each result is published, and what has not been done yet. Reporting a vulnerability is covered by the security policy.

Looking something up

The Reference section is generated from the server’s own source on every build, so it describes the release the site was built from; nothing in it is maintained by hand:

• Settings — every server-wide flag and option, what it does, and whether changing it needs a restart.
• Endpoints — every route the server serves, which feature flag governs it, and its CORS and rate-limit class.
• Admin API — the management API behind the console.
• MCP tools — the operations an AI agent may perform, an allow-list chosen on purpose and narrower than the whole admin surface.
• Addon seams — the named functions you replace with your own instead of forking.
• Environment variables — what has to be set before the server will start.

What this server is not

It speaks OAuth 2.1 and OpenID Connect, and nothing else. There is no SAML support and none planned. The Implicit and Resource Owner Password Credentials grants are not implemented, because OAuth 2.1 removes them. If an application depends on either, it needs changing before it can use this server.

If you are still deciding whether to run it at all, the comparisons put it beside the servers teams usually weigh it against, with the date each claim was checked.