Overview
Much of what Stalwart offers travels over HTTP: the modern client protocols, the sign-in flows, the documents that let clients configure themselves, the monitoring endpoints and the web interface. All of these share the server’s HTTP listeners. Every HTTP listener serves the same set of endpoints, whether it is the https listener on port 443 or the http listener on port 8080 of a new installation.
The endpoints fall into a few groups. The JMAP, CalDAV, CardDAV and WebDAV protocols serve clients. The OAuth authorization server handles sign-in. Discovery documents let clients configure themselves. Operational endpoints provide health checks and metrics, and the management API lets tools administer the server. Finally, web applications such as the WebUI provide the interface for people.
The server-wide behaviour of these endpoints is configured on the HTTP server page, and access control rules decide which of them each client may reach. This page lists the endpoints by group.
Endpoints marked as authenticated require credentials. A client can authenticate with HTTP Basic authentication, using an account’s password or an app password, or with a Bearer token, which is an OAuth access token or an API key. Public endpoints are open to anyone, so they are subject to the anonymous rate limit.
Client protocols
Section titled “Client protocols”| Path | Serves | Authentication |
|---|---|---|
/jmap/ | JMAP API requests (POST) | Required |
/jmap/session | The JMAP session resource, which lists the account’s capabilities and the URLs below | Required for the account’s session; without credentials it returns only the server’s capabilities |
/jmap/upload/<accountId>/, /jmap/download/... | Blob upload and download | Required |
/jmap/eventsource | Push notifications over Server-Sent Events | Required |
/jmap/ws | The JMAP WebSocket endpoint | Required |
/dav/cal/, /dav/card/, /dav/file/ | CalDAV, CardDAV and WebDAV collections | Required, except OPTIONS |
/dav/pal/, /dav/itip/ | DAV principals and calendar scheduling | Required, except OPTIONS |
Authentication and OAuth
Section titled “Authentication and OAuth”| Path | Serves | Authentication |
|---|---|---|
/login, /device | The OAuth sign-in and device-code pages, used by OAuth clients, the WebUI and the account manager; /login is not a webmail login | None |
/auth/token, /auth/device, /auth/revoke, /auth/register, /auth/logout, /auth/jwks.json | OAuth token, device authorization, revocation, client registration, sign-out and signing keys | None (client authentication where the protocol requires it) |
/auth/introspect, /auth/userinfo | Token introspection and OpenID Connect user information | Required |
OAuth endpoints describes each of them.
Discovery
Section titled “Discovery”| Path | Serves |
|---|---|
/.well-known/jmap | Redirect (307) to /jmap/session |
/.well-known/caldav, /.well-known/carddav | Redirect (307) to /dav/cal and /dav/card |
/.well-known/oauth-authorization-server, /.well-known/openid-configuration | OAuth and OpenID Connect metadata |
/.well-known/oauth-protected-resource | Protected resource metadata (RFC 9728) |
/.well-known/user-agent-configuration.json | The PACC client configuration document |
/.well-known/autoconfig/mail/config-v1.1.xml, /.well-known/mail-v1.xml, /mail/config-v1.1.xml | Mozilla autoconfig |
/autodiscover/autodiscover.xml, /autodiscover/autodiscover.json | Outlook Autodiscover |
/.well-known/mta-sts.txt | The MTA-STS policy |
/.well-known/acme-challenge/<token> | The ACME HTTP-01 challenge, when a provider uses it |
All of these endpoints are public. Autoconfiguration describes the client configuration documents.
Operations
Section titled “Operations”| Path | Serves | Authentication |
|---|---|---|
/healthz/live | Liveness: 200 while the server process runs | None |
/healthz/ready | Readiness: 200 when the data store is available, 503 otherwise | None |
/metrics/prometheus | Prometheus metrics, when the exporter is enabled | The exporter’s own credentials |
/api/... | The management HTTP API: sign-in, account information, schema, live telemetry and delivery tests | Required, except the sign-in endpoints |
/scim/v2/... | SCIM provisioning (Enterprise) | Required |
/form/... | Form submission, when enabled | None |
/calendar/rsvp | The RSVP page for calendar invitations, when enabled | None (signed link) |
/logo | The logo of the domain or tenant (Enterprise) | None |
/robots.txt | A file that asks crawlers to index nothing | None |
Web applications
Section titled “Web applications”/admin and /account serve the WebUI’s administration console and account manager, which are installed as applications. Other applications are served under their own prefixes. The files of an application are public, because the application itself signs in through OAuth. A request for / is redirected to the path in Http.redirectRoot.
A request for any other path returns 404. Some unknown paths are treated as an attack, however. A request for an unknown path that matches one of the scan patterns of auto-ban, such as a path containing .php or wp-, bans the client’s address.