Public endpoints
Most of the API needs a signed-in user. A few endpoints answer without any credentials, for a visitor who is not signed in. This page lists them, what they return and what they refuse. All paths are under /api/v1.
Two path prefixes tell the routes that need no credential apart. The routes that obtain, renew or end a session (/auth/login, /auth/mfa/verify, /auth/password-change, /auth/sessions/{session_id}/tokens, /auth/refresh and /auth/logout) live under /auth. Every other route a visitor can call without signing in lives under /public. The exceptions are the version and health probes (/about, /health) and the signed media URLs (/activities/{activity_id}/thumbnail, /activities/{activity_id}/media/{media_id}/file, /users/{user_id}/photo, where {user_id} is a UUID), which an image tag follows without a header.
Public endpoints send no Authorization or X-Client-Type header. They are rate limited per client network, an IPv4 address or an IPv6 /64 (see Errors, concurrency and rate limits), so set TRUSTED_PROXIES correctly behind a proxy. Reads use the default limit, the shared streams 30 per minute.
Shared activities
These serve an activity that its owner made public. They work only when an administrator has enabled public shareable links. {activity_id} and {media_id} are UUIDs.
| Method and path | Returns |
|---|---|
GET /public/activities/{activity_id} |
The activity |
GET /public/activities/{activity_id}/detail |
The activity with its owner's public profile (owner: id, name, username, city and photo URL) and the first page of its laps, workout sets and workout steps in one read |
GET /public/activities/{activity_id}/laps |
A page of laps |
GET /public/activities/{activity_id}/sets |
A page of workout sets |
GET /public/activities/{activity_id}/workout-steps |
A page of workout steps |
GET /public/activities/{activity_id}/streams |
A page of streams |
GET /public/activities/{activity_id}/streams/{stream_type} |
One stream |
GET /public/activities/exercise-titles |
The exercise title reference table |
flowchart TD
R[Anonymous request for an activity] --> L{Public links enabled?}
L -- no --> N[404]
L -- yes --> P{Activity is public and not hidden?}
P -- no --> N
P -- yes --> H[Hidden details are removed]
H --> OK[200]
What to expect:
- 404 for everything that is not shareable. An activity that does not exist, is not public, is hidden, or whose links are switched off all answer
404with the same body, so an id cannot be probed to see which activities exist. - Hidden details are removed. What the owner chose to hide from others (location, map, heart rate and so on) is missing from the response, and the laps, sets, streams and steps of an activity that hides them are not served.
- The owner needs two settings.
ownerin the detail is filled only when public links and Show user info on public links are both on; otherwise it isnulland the rest of the detail is served. There is no public lookup of a user by id. It never includes an email, birthdate or access level. - Lists are paged with
page_numberandnum_records(the same envelope as the authenticated lists).
Signed media links
Thumbnails, activity photos and profile photos are served by URLs that carry a signed token in the query string. They need no login so that they work in an <img src>, and the signature is the access control.
| Path | Carries |
|---|---|
GET /activities/{activity_id}/thumbnail?t=<token> |
The activity's map preview (WebP) |
GET /activities/{activity_id}/media/{media_id}/file?t=<token> |
One activity photo |
The photo_path URL in a user |
A profile photo |
How the link looks depends on where the server keeps its files (the STORAGE_URI setting, see Storage and backups):
| Storage | The link | Lifetime |
|---|---|---|
| Local disk | The paths above, with ?t=<token>, a token signed with the server's SECRET_KEY |
18 to 24 hours from the read that returned it (see below) |
| S3 or an S3-compatible service | A presigned URL on the storage service's own origin. It has no ?t= token and does not pass through the API |
1 hour |
You do not build these URLs. The API puts a ready-to-use URL in the field of the response (map_thumbnail_url, a media item's URL, a user's photo_path), and it only does so for something the caller may see. Treat them as opaque:
- Reading the activity or user again returns a fresh link, so a client should use the URL from the response it just received, not store it. A presigned S3 link lasts only 1 hour, so do not keep it longer than that.
- A local token is stamped with the start of a 6-hour window, not the second it was signed, so reading the same thing again within that window returns the same URL and the browser can reuse its cached copy. A token is valid for 24 hours from the start of its window, so a link is good for at least 18 hours from the read that returned it, and never for more than 24. The next window returns a new URL.
- A
?t=token is derived from the server'sSECRET_KEY, so changing the key makes every previously issued local link stop working until it is fetched again. It does not affect presigned S3 links. - A local link that is wrong, forged or expired answers
404. An S3 link is checked by the storage service, which answers with its own error. - Local responses are cacheable by the browser for an hour (
Cache-Control: private, max-age=3600), well inside the 18 hours a link is always good for, so a cached copy never outlives its link. - A browser fetches S3 links from the storage origin, so a client that sets its own content security policy must allow it.
- Anyone who holds a link can open that one file until it expires. Do not post links from a private activity.
Server information
| Method and path | Returns |
|---|---|
GET /about |
API name, version and licence. Does not touch the database |
GET /health |
{"status", "state", "audit"}: status is ok, or degraded when the shared state backend does not answer (state is unavailable) or the audit trail is unhealthy (audit is degraded), still with 200. 503 with Retry-After when the database does not answer. See Monitoring |
GET /public/server-settings |
The public subset of the server settings: units, currency, records per page, whether sign-up, SSO and local login are on, whether a new sign-up must verify its email address (signup_require_email_verification), the SSO auto-redirect flag, the public sharing flags, the tile server URL, attribution and background colour, the minimum password lengths (so the sign-up form can validate), whether a login photo is set and the allowed SSO redirect addresses. The sign-up approval switch, geocoding, session and retention settings, API keys and every other secret are not included |
GET /public/server-settings/tile-maps-templates |
The map tile presets an administrator can pick |
GET /public/idp/{slug}/icon |
The image uploaded for an identity provider, or 404 if it has none. Supports ETag and If-None-Match |
GET /public/server-settings/login-photo |
The login page photo, or 404 if none is set. Supports ETag and If-None-Match, so a client that has the photo gets 304 |
The server settings are public by design: the login page needs them before anyone signs in. That includes the tile URL, so do not put a secret in it. See Map tile server.
Sign-in and account flows
These need no credentials because their job is to obtain them. They are documented with the flows they belong to:
| Path | Purpose | See |
|---|---|---|
POST /auth/login, /auth/mfa/verify, /auth/password-change, /auth/sessions/{session_id}/tokens, /auth/refresh, /auth/logout |
Password login, MFA, the password change an administrator-set password requires, the exchange of a mobile or SSO session for tokens, and token refresh; every answer but logout's carries a next_step; logout answers 200 with idp_logout_url, the identity provider's end-session URL or null |
Handling authentication |
GET /public/idp, /public/idp/login/{slug}, /public/idp/callback/{slug}, /public/idp/link |
Single sign-on and the system-browser hand-off of an account link (?ticket=); the session it starts is exchanged at POST /auth/sessions/{session_id}/tokens |
OAuth/SSO and PKCE |
POST /public/idp/{slug}/backchannel-logout |
Called by the identity provider, not by a client: an OpenID Connect Back-Channel Logout request with a signed logout_token (form-encoded). Answers 200 with no body and Cache-Control: no-store when the sessions it names have ended or none was signed in, 400 for a refused token, 404 for a provider that is unknown or issues no ID token (a disabled provider is still served, so a logout token for a sign-in recorded before it was disabled still succeeds), 422 for a missing token and 503 when the replay check cannot run |
OAuth/SSO and PKCE |
POST /public/sign-up/request, /public/sign-up/confirm, /public/sign-up/resend, /public/email-change/confirm |
Create an account, confirm its sign-up link and send that link again; all answer 200 with a next_step (see Confirming a link). /public/email-change/confirm confirms an email change and answers 204 with no body. /public/sign-up/request is 400 with urn:endurain:error:password-required when the server does not require email verification and the request carries no password. /public/sign-up/request and /public/sign-up/resend are 403 with urn:endurain:error:permission-denied while sign-up is turned off, checked first and whatever the address or password, so the answer reveals nothing; /public/sign-up/confirm is the same 403 while sign-up is turned off when the token belongs to a pending sign-up (the link stays usable), but an account an administrator activated without a password can still choose one from its link; /public/email-change/confirm is not a sign-up and is unaffected. /public/sign-up/confirm is also 403 with urn:endurain:error:email-verification-disabled while the server does not require email verification and the token belongs to a pending self sign-up; an administrator's invitation link (an active account without a password) is confirmed whatever the email-verification setting |
Accounts, sign-up and password reset |
POST /public/email-change/cancel |
Report an email change as not made by the account's owner, with the token of the link emailed to the account's address; it works once, for 7 days after the change was requested, whatever happened to the change since: confirmed, pending, replaced by a later request or expired unconfirmed. Answers 200 with {"change_applied", "email_restored"}; 400 (invalid-input, "Invalid or expired link") for a malformed, forged or expired token, or one that names a change already reverted (a second use, or a later change whose run an earlier link already reverted). It reverts its change and every later change of the account still inside its window and not reverted, voids every unused confirmation link of the account so a pending change cannot be confirmed afterwards, puts the address the link was mailed to back when any of those changes was confirmed (unless another account holds that address; the address is reserved for the account during the window), and always secures the account: it ends every session, revokes the API keys and the unused password-reset tokens, and does not change the password |
Email change |
POST /public/password-reset/request, /public/password-reset/confirm, /public/password-reset/validate |
Reset a forgotten password; all three answer 204 with no body, and the request answers the same for a known and an unknown address. A confirmation for an account whose email was never verified also removes its identity-provider links, MFA factors and backup codes, and marks the email verified; the auth.password.reset audit row's unverified_account_cleaned detail records it |
Accounts, sign-up and password reset |
GET /public/onboarding, POST /public/onboarding |
Create the first administrator of a new installation | First-run onboarding |
The sensitive ones (login, MFA, sign-up, reset, onboarding) have a tighter 10 requests per minute limit.
Confirming a link
Each emailed link names its kind in its frontend path, and each kind has its own route:
| Link | Frontend path | Route | Body |
|---|---|---|---|
Sign-up verification (also sent again by /public/sign-up/resend), and the invitation of an account an administrator created without a password (see Password change at sign-in) |
/signup/confirm#token=… |
POST /public/sign-up/confirm |
{"token", "password"} |
| Email change, sent to the new address | /confirm-email-change#token=… |
POST /public/email-change/confirm |
{"token"} |
The token travels in the URL fragment (#token=…), which a browser never sends to a server, so it stays out of proxy and access logs and Referer headers. The reset link is /reset-password#token=… and the cancel link of an email change notice is /cancel-email-change#token=…. A frontend reads the token from the fragment, then removes it from the address bar and keeps it in memory only. Opening a link changes nothing: the email change is confirmed or cancelled only when the person presses the button on the page, so a mail scanner that opens the link cannot do it.
A route refuses a token of the other kind with 400, the same problem an unknown, used or expired token gets, and leaves the token usable for its own route.
- Confirming a sign-up. The account chooses its password here, so
passwordis required (a missing one is422). The account then becomes active, or goes on to the administrators' approval when the server requires it. An account an administrator activated before it was confirmed has no password yet and chooses one the same way; an account that takes no password from a link (one an administrator deactivated, or one that already has a password) is400. The password ends every session of the account (see Ending other sessions). - Confirming an email change. The account switches to the confirmed address (see Email Change); the body carries no
password, and the answer is204. It is409when another account holds the address now.
The sign-up routes (/public/sign-up/request, /public/sign-up/confirm, /public/sign-up/resend) answer {"next_step"}, one of the values below. The set is open: a client treats a value it does not know as an unsupported step, shows a generic error and does not guess. The email-change route is not a sign-up: it answers 204 with no body once the change is confirmed, and the user signs in with the new address.
next_step |
Meaning |
|---|---|
sign_in |
The account is ready; the user signs in. |
check_email |
A verification email was sent (or, for a resend, may have been); the user opens its link. |
await_approval |
An administrator must approve the account before it can sign in. |
A sign-up request answers from the server's policy alone: check_email when email verification is required, else await_approval when admin approval is required, else sign_in. A resend always answers check_email. Neither depends on whether the address is registered.
First-run onboarding
A new installation has no account. These two endpoints create the first administrator, and only while the installation has no account at all. See First sign-in.
| Method and path | Returns |
|---|---|
GET /public/onboarding |
{"onboarding_required": true} while no account exists, otherwise false. Once an account exists it never becomes true again |
POST /public/onboarding |
Body {"token", "name", "username", "email", "password"}. Creates an active administrator with a verified email and answers 201 with the user |
What to expect from POST /public/onboarding:
- The token comes from the server log. While no account exists, every API worker logs a one-time setup token at startup (field
setup_token). It is valid for 24 hours and works once; a restart prints a new one. 409once any account exists. The endpoint never creates a second account, whatever the token.400for a token that is unknown, expired or already used.422for a password the password rules refuse (problem typeurn:endurain:error:password-too-short,password-too-common,password-breached,password-matches-accountorpassword-blank), or for an unknown field. The role and account state are not accepted from the client.- Two requests at the same time still create one administrator: the other answers
409.
Not public
For clarity, these are never served without credentials: user lists and profiles beyond the one public projection above, activities that are not public, follower lists, health data, notifications and settings. The WebSocket also needs a ticket; see Realtime updates.