Changes from v0.20 to v0.21
What changed between v0.20 and v0.21 for the people who run Endurain and for the clients that call its API: third-party apps, mobile apps and scripts that use API keys. If you only use the Endurain web app, you need only the first section. For the rules that hold from now on, see Compatibility between releases.
Before you upgrade
Back up the database and the data folder first. The upgrade converts every integer id to a UUID and cannot be undone: restoring the backup is the only way back to v0.20.
- Upgrade from v0.20.x only, with every data migration finished. The first revision refuses to run on a database that has users and a pending v0.20 data migration, and says which ones. Start the latest v0.20.x release, let the data migrations finish, then upgrade.
- Stop every Endurain process (web and worker containers) before the upgrade, so nothing runs against the old schema while it converts.
- A provider slug can be a reserved word. The upgrade refuses to run while an identity provider uses the slug
login,callback,iconorbackchannel-logout. Change the slug and register the new callback URL (<ENDURAIN_HOST>/api/v1/public/idp/callback/<slug>) at the provider, then upgrade again. A new or renamed provider cannot uselinkeither. - Two providers cannot share an issuer. The upgrade refuses to run while two identity providers have the same issuer URL (trailing slashes ignored). Change the issuer URL of, or delete, all but one.
- Everyone signs in again once. Every web and mobile session ends. API keys keep working, and keys that never expired now expire 365 days after the upgrade (see API keys).
- Single sign-on stops creating accounts. The new setting Allow new user sign-ups through single sign-on is off after the upgrade, so a first sign-in that matches no account is refused with
sso_auto_create_disabled. Existing accounts sign in and link as before. Turn it on in Settings > Server settings if providers should keep creating accounts. Existing providers keep linking by email and syncing the email as they did (link_by_emailon,sync_emailset fromsync_user_info); a new provider starts with both off. - Stored files and folders are renamed to the new UUIDs at the first start: activity files, thumbnails and media, identity-provider icons, profile photos, failed bulk-import files, staged profile exports and imports, and the per-user bulk import and Strava import folders. Account lockouts are lifted. See Storage and backups.
- The schema upgrade runs in one transaction and takes longer on a large database. Run
VACUUM (ANALYZE)on the database afterwards, for exampledocker exec -it <postgres container> psql -U endurain -d endurain -c 'VACUUM (ANALYZE);'.
Environment variables
See Supported environment variables for the full list.
| Variable | What happens |
|---|---|
ALLOWED_REDIRECT_SCHEMES |
Removed. Endurain refuses to start while it is set. List the exact redirect addresses in ALLOWED_REDIRECT_URIS instead: a scheme allowed every address under it, an entry allows only itself (see Mobile app redirect). |
ALGORITHM |
No longer read. Tokens are always signed with HS256. A leftover value (or ALGORITHM_FILE) is ignored with a warning. |
SESSION_IDLE_TIMEOUT_ENABLED, SESSION_IDLE_TIMEOUT_HOURS, SESSION_ABSOLUTE_TIMEOUT_HOURS, ACCESS_TOKEN_EXPIRE_MINUTES, REFRESH_TOKEN_EXPIRE_DAYS |
Deprecated. Now Settings > Server settings > Access & security. |
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM, SMTP_SECURE, SMTP_SECURE_TYPE |
Deprecated. Now Settings > Server settings > Email. |
REVERSE_GEO_PROVIDER, PHOTON_API_HOST, PHOTON_API_USE_HTTPS, NOMINATIM_API_HOST, NOMINATIM_API_USE_HTTPS, GEOCODES_MAPS_API, REVERSE_GEO_RATE_LIMIT |
Deprecated. Now Settings > Server settings > Maps & location. |
READ_NOTIFICATION_RETENTION_DAYS |
Deprecated. Now Settings > Server settings > General. |
ENVIRONMENT |
Must be production, demo or development. Any other value stops Endurain at startup. |
BEHIND_PROXY |
true now requires a usable TRUSTED_PROXIES entry: the container refuses to start without one (it used to log an error and start). |
TRUSTED_PROXIES |
No longer defaults to * in development. |
LOG_ACCESS |
New. The per-request access log is off unless it is true. |
ENDURAIN_HOST |
Must be only scheme://host[:port], with no path, query, fragment or user info, or Endurain refuses to start. It is read in canonical form (lower-case scheme and host, default port dropped), and the token iss and aud use that form. |
SECRET_KEY |
At least 32 characters with at least 10 distinct ones. List several keys separated by commas to rotate it: the first signs, all of them verify. |
FERNET_KEY |
List several keys separated by commas to rotate it: the first encrypts, all of them decrypt. |
SECRET_KEY, FERNET_KEY, DB_PASSWORD |
The example values published in .env.example and in the docs are refused at startup, including through the *_FILE variants. |
The deprecated variables that moved to the admin settings are still read. At every start, Endurain saves the ones that are set into the database, logs one warning naming them, and shows those settings as read-only while the variables are set. The email variables are read only when SMTP_HOST is set, an invalid email or geocoding value is skipped with a warning and the stored setting kept, and session values that contradict each other (an absolute timeout below the idle timeout, an access token lifetime not below the idle timeout) stop Endurain at startup. Remove the variables after the first start. From v0.22.0 Endurain refuses to start while any of them is set.
Mobile app redirect
The default ALLOWED_REDIRECT_URIS is com.endurain.endurain:/auth/sso/callback. If you serve app builds that send endurain://auth/sso/callback, add that address to the list, and keep the default in it, because setting the variable replaces the default:
ALLOWED_REDIRECT_URIS=com.endurain.endurain:/auth/sso/callback,endurain://auth/sso/callback
An app listed there receives tokens with every scope the signing-in user holds, so list only apps you trust. See Redirect schemes.
Authentication and sessions
Tokens
- Tokens issued before the upgrade are refused. The
subclaim is the user's UUID. Tokens carrytypandkidheaders (thetypclaim is gone), and a newclient_typeclaim (webormobile). Thescopeclaim is a space-separated string instead of a JSON list. Access and refresh tokens are signed with separate keys and carry a differentaud. Treat tokens as opaque, as Compatibility says. - Cookies. The refresh cookie is set with
Path=/instead of/api/v1/auth. Two cookies are new: the device cookie (endurain_device) and the identity-provider binding cookie (endurain_idp_binding). Inproductionanddemoall three carry the__Host-prefix. A web browser signs in again after the upgrade and counts as a new device once.
Signing in
- Sign-in steps. Every answer of
POST /auth/login,POST /auth/mfa/verify,POST /auth/password-changeandPOST /auth/sessions/{session_id}/tokenscarries a requirednext_step:mfa(withmfa_challengeandmethods),password_change(withpassword_change_challenge),exchange(mobile:session_idanddevice_id) ortokens.mfa_required,usernameandmessageare gone, andPOST /auth/loginanswers200for every step (a web client's MFA step was202). Switch onnext_step; a value the client does not know means the app needs an update, so stop the sign-in and keep no partial state. See Sign-in steps. X-Client-Typeon the/auth/routes: a missing or unknown value is422instead of400.- Token exchange route. The PKCE exchange moved from
POST /public/idp/session/{session_id}/tokenstoPOST /auth/sessions/{session_id}/tokens, for password and SSO sign-ins alike. ItsX-Client-Typemust match the one the sign-in started with (400otherwise), and its body takes onlycode_verifier(any other member is422). - PKCE on mobile password sign-in.
code_challengeandcode_challenge_methodare form fields ofPOST /auth/login, next tousernameandpassword, instead of optional query parameters. Both are required formobileand refused forweb. A mobile password sign-in finishes withexchange, never tokens. - MFA step.
POST /auth/mfa/verifytakes{"mfa_challenge": …, "mfa_code": …}: the challenge from the previous step replacesusername, and the request carries no PKCE values. The challenge lives 5 minutes; the first two wrong codes are400and the third ends it with401, after which the client restarts the sign-in. - SSO sign-in with MFA. An SSO sign-in now asks for the account's Endurain second factor. For an account with MFA,
POST /auth/sessions/{session_id}/tokensanswers200withnext_step: "mfa", and the client finishes atPOST /auth/mfa/verifywith the sameX-Client-Type, which answers the tokens directly, never a second session to exchange. - Password change at sign-in is new. When an administrator set the account's password, sign-in answers
next_step: "password_change"and creates no session. The client asks for a new password and sends it with the challenge toPOST /auth/password-change, which answersexchange(mobile) ortokens(web). See Password change at sign-in. - Known devices are new. A mobile client sends
X-Device-Idon/auth/login,/auth/mfa/verify,/auth/password-changeand the token exchange, with thedevice_idthe server returned on an earlier sign-in; a browser sends the device cookie. A sign-in from a device the account does not know sends the user a new-device notice, so a client that does not send its id makes every sign-in a new device. Store the id next to the tokens. Devices are listed and forgotten under/profile/devices.
Refresh and logout
- Mobile refresh and logout.
POST /auth/refreshandPOST /auth/logouttake the refresh token in the JSON body,{"refresh_token": "…"}, instead of theAuthorizationheader, which carries access tokens only. Both token bodies carrynext_step: "tokens"andrefresh_token_expires_in. - Logout answers
200with{"idp_logout_url": …}instead of{"message": …}, also for a refresh token that is missing, expired or already revoked (it was401). Open the URL in the system browser to also end the provider session, or ignore it. - No CSRF token. The web token responses no longer carry
csrf_token, andX-CSRF-Tokenis neither read nor allowed.POST /auth/refreshandPOST /auth/logoutfrom a web client must carry anOriginheader the server allows (browsers add it) and are refused with403whenSec-Fetch-Siteiscross-site. See Authentication.
Errors
- Sign-in errors. Every refusal of
POST /auth/refresh, and a dead pending sign-in atPOST /auth/mfa/verifyandPOST /auth/password-change, is401withurn:endurain:error:session-endedandWWW-Authenticate: Session: sign in again, do not retry. A failed password sign-in challenges withSession, notBearer.invalid-tokenmeans "refresh once and replay the request" on resource routes only. See Authentication errors. - One
429type. Every429istoo-many-requests, with ascopemember (requests,sign-in,mfa,step-up,provider,follow-request).rate-limitedis gone. - Missing scope. A
403for a missing scope carriesWWW-Authenticate: Bearer error="insufficient_scope", scope="…"and amissing_scopesmember. - Required MFA is new: when an administrator requires two-step verification, an account it covers without MFA gets
403withurn:endurain:error:mfa-enrolment-requireduntil it sets it up.
Step-up and account security
- Step-up. Sensitive requests carry one
step_upobject instead of the flatcurrent_passwordandmfa_codefields:current_password,mfa_code, and for an account without a passwordidp_reauth. A step-up that does not verify is403withurn:endurain:error:step-up-failed(it was401). An account without a password that sends noidp_reauthgets401withurn:endurain:error:idp-reauth-required, and a locked-out one429with scopestep-up. See Operations that require step-up. - MFA reads.
GET /profile/mfa/statusgainsfactors, and the MFA step of a sign-in gainsmethods. Both are open sets. - Sessions. Session reads carry
is_currentandapp_redirect_uri, and session lists are paged.last_loginof an identity-provider link islast_login_at. - Signing out everywhere.
DELETE /profile/sessionsended the other sessions only. Its replacement,POST /profile/sessions/revoke, ends every session including the current one, unless the body sendskeep_current: true. - API keys always expire (365 days by default; an administrator sets the maximum, 1 to 3650 days), and an account holds at most 25 active keys (
409withurn:endurain:error:api-key-limit).scopesis an array instead of a string. A key could hold onlyactivities:upload; it can now hold the data scopes listed in API keys, never theaccount:security,account:export,account:integrationsor administrator scopes.
Scopes
A scope name is lower-case kebab-case. The old names are refused like any unknown scope. See Available scopes.
| Old scope | New scope |
|---|---|
profile |
account, split as described below |
health_targets:read, health_targets:write |
health-targets:read, health-targets:write |
identity_providers:read, identity_providers:write |
identity-providers:read, identity-providers:write |
server_settings:read, server_settings:write |
server-settings:read, server-settings:write |
profilewas split. Security operations (password, MFA, sessions, devices, API keys, identity-provider links, closing the account) needaccount:security, profile export and import needaccount:export, and linking and unlinking Garmin Connect and Strava (andPUT /strava/client) needaccount:integrations. Every user holds all three. The Garmin and Strava sync and import routes need the data scopes instead (activities:write,gears:write,health:write).- Health targets used
health:readandhealth:writein v0.20; they now needhealth-targets:readandhealth-targets:write. identity-providers:readis administrator-only. Regular users heldidentity_providers:readin v0.20.- New administrator scopes:
users:read-all,api-keys:read,api-keys:write,server-settings:logsandserver-settings:logs-clear. - Enforcement. A token's scopes are limited at every request to the scopes the user's role holds then, so a demotion applies at the next request; v0.20 trusted the token's claim. An API key holds the scopes it was created with, limited the same way by its owner's role.
Identifiers and values
The ids of users, activities and their laps, sets, steps, streams and media, gear and components, health records, goals, notifications, identity providers and their links are UUID strings instead of integers. Session, API key and job ids were already UUID strings. Exercise titles keep integer ids, and the Strava and Garmin ids (strava_activity_id, garminconnect_activity_id) stay numbers.
- A malformed id in a path, query or body answers
422, and an unknown one404. - Do not assume a format or an order. Treat
idas a string, also in the public provider list (GET /public/idp). - An activity feed cursor issued before the upgrade answers
400. Restart the feed without a cursor. - Public share links and saved activity links from before the upgrade stop working, because the link carries the activity id. Share the activity again.
- Enums are strings.
activity_type, activityvisibility, mediamedia_type, streamstream_typeand notificationtypewere integers and are now string names. The activity types are the keys ofGET /activities/types(see Data conventions). The keys of the activity stats follow the same names:snowshoeing,stand_up_paddleboardingandsurfingaresnow_shoeing,stand_up_paddlingandsurf, andotheris new. - Booleans.
is_strava_linkedandis_garminconnect_linkedof the profile are booleans instead of0or1. - Prices (
purchase_value,total_components_cost) are decimal strings such as"129.90"instead of numbers.
Routes
Paths are under /api/v1. Routes not listed kept their method and path. A row without a new route was removed.
Sign-in and public flows
| v0.20 | v0.21 |
|---|---|
POST /public/idp/session/{session_id}/tokens |
POST /auth/sessions/{session_id}/tokens |
POST /sign-up/request, POST /sign-up/confirm |
POST /public/sign-up/request, POST /public/sign-up/confirm |
POST /password-reset/request, POST /password-reset/confirm |
POST /public/password-reset/request, POST /public/password-reset/confirm |
GET /public/server_settings |
GET /public/server-settings |
GET /public/server_settings/tile_maps_templates, GET /server_settings/tile_maps_templates |
GET /public/server-settings/tile-maps-templates |
GET /server_images/{server_img} |
GET /public/server-settings/login-photo |
GET /public/users/id/{user_id} |
Your profile
| v0.20 | v0.21 |
|---|---|
PUT /profile |
PATCH /profile |
POST /profile/image |
PUT /profile/photo |
PUT /profile/photo (removed the photo) |
DELETE /profile/photo |
PUT /profile/password |
POST /profile/password/change |
PUT /profile/privacy |
PATCH /profile/privacy |
GET /profile/default_gear, PUT /profile/default_gear |
GET /profile/default-gear, PATCH /profile/default-gear |
PUT /profile/goals |
PUT /profile/goals/{goal_id} |
GET /profile/export |
POST /profile/export, then GET /profile/export/download |
DELETE /profile/sessions |
POST /profile/sessions/revoke |
PUT /profile/mfa/enable, PUT /profile/mfa/disable |
POST /profile/mfa/enable, POST /profile/mfa/disable |
POST /profile/mfa/verify |
|
GET /profile/api_keys, POST /profile/api_keys, DELETE /profile/api_keys/{api_key_id} |
GET /profile/api-keys, POST /profile/api-keys, DELETE /profile/api-keys/{api_key_id} |
PATCH /profile/api_keys/{api_key_id}/revoke |
POST /profile/api-keys/{api_key_id}/revoke |
GET /profile/idp |
GET /profile/identity-providers |
GET /profile/idp/{idp_id}/link |
POST /profile/identity-providers/{idp_id}/link |
POST /profile/idp/{idp_id}/link/token |
|
POST /profile/idp/{idp_id}/unlink |
POST /profile/identity-providers/{idp_id}/unlink |
GET /followers/follow-requests |
GET /profile/follow-requests |
PATCH /followers/follow-requests/{follower_id} |
POST /profile/follow-requests/{follower_id}/accept |
DELETE /followers/follow-requests/{follower_id} |
DELETE /profile/follow-requests/{follower_id} |
Users, followers and sessions
| v0.20 | v0.21 |
|---|---|
GET /users/id/{user_id} |
GET /users/{user_id} |
GET /users/username/{username} |
GET /users?username= |
GET /users/username/contains/{username} |
GET /users?username_contains= |
GET /users/email/{email} |
|
PUT /users/{user_id} |
PATCH /users/{user_id} |
DELETE /users/{user_id} |
POST /users/{user_id}/delete |
PUT /users/{user_id}/approve |
POST /users/{user_id}/approve |
PUT /users/{user_id}/password |
POST /users/{user_id}/password/change |
POST /users/{user_id}/image |
PUT /users/{user_id}/photo |
DELETE /users/{user_id}/identity-providers/{idp_id} |
POST /users/{user_id}/identity-providers/{idp_id}/unlink |
GET /sessions/user/{user_id} |
GET /users/{user_id}/sessions |
DELETE /sessions/user/{user_id} |
POST /users/{user_id}/sessions/revoke |
DELETE /sessions/{session_id}/user/{user_id} |
POST /users/{user_id}/sessions/{session_id}/revoke |
GET /activities/users/{user_id}, GET /activities/users/{user_id}/stats |
GET /users/{user_id}/activities, GET /users/{user_id}/activities/stats |
/followers/users/{user_id}/followers (GET, POST) |
/users/{user_id}/followers (GET, POST) |
DELETE /followers/users/{user_id}/followers/{follower_id} |
DELETE /users/{user_id}/followers/{follower_id} |
GET /followers/users/{user_id}/following |
GET /users/{user_id}/following |
GET /followers/users/{user_id}/relationship |
GET /users/{user_id}/relationship |
Activities, gear and health
| v0.20 | v0.21 |
|---|---|
GET /activities/ingestion-jobs/{job_id} |
GET /jobs/{job_id} |
GET /activities/gears/{gear_id} |
GET /activities?gear_id= |
GET /activities/exercise-titles/all, GET /public/activities/exercise-titles/all |
GET /activities/exercise-titles, GET /public/activities/exercise-titles |
GET /gears/id/{gear_id} |
GET /gears/{gear_id} |
PUT /gears |
PATCH /gears/{gear_id} |
GET /gears/nickname/contains/{nickname} |
GET /gears?nickname_contains= |
GET /gears/type/{gear_type} |
GET /gears?gear_type= |
GET /gears/nickname/{nickname} |
|
GET /gear_components, POST /gear_components |
GET /gear-components, POST /gear-components |
PUT /gear_components |
PATCH /gear-components/{gear_component_id} |
DELETE /gear_components/{gear_component_id} |
DELETE /gear-components/{gear_component_id} |
GET /gear_components/types |
GET /gear-components/types |
GET /gear_components/gear_id/{gear_id} |
GET /gears/{gear_id}/components |
PUT /health/weight, /health/sleep, /health/steps, /health/water, /health/fasting, /health/poop (id in the body) |
PATCH /health/weight/{id} and likewise for each kind (id in the path) |
PUT /health/targets |
PATCH /health/targets |
Notifications and integrations
| v0.20 | v0.21 |
|---|---|
GET /notifications/page_number/{page_number}/num_records/{num_records} |
GET /notifications (cursor) |
GET /notifications/number |
GET /notifications/unread-count |
PUT /notifications/{notification_id}/mark_as_read |
POST /notifications/{notification_id}/read |
PUT /notifications/mark_all_as_read |
POST /notifications/read |
GET /garminconnect/activities, GET /garminconnect/gear, GET /garminconnect/health |
POST /garmin/activities, POST /garmin/gear, POST /garmin/health |
POST /garminconnect/link, POST /garminconnect/mfa |
POST /garmin/link, POST /garmin/mfa |
DELETE /garminconnect/unlink |
POST /garmin/unlink |
GET /strava/activities, GET /strava/gear |
POST /strava/activities, POST /strava/gear |
PUT /strava/link |
POST /strava/link |
PUT /strava/state/{state} |
POST /strava/state (the server issues the state) |
DELETE /strava/unlink |
POST /strava/unlink |
POST /strava/import/bikes, POST /strava/import/shoes |
POST /strava/import/gear |
Administration
| v0.20 | v0.21 |
|---|---|
GET /idp, POST /idp |
GET /identity-providers, POST /identity-providers |
GET /idp/templates |
GET /identity-providers/templates |
PUT /idp/{idp_id} |
PATCH /identity-providers/{idp_id} |
DELETE /idp/{idp_id} |
POST /identity-providers/{idp_id}/delete |
GET /server_settings, PUT /server_settings |
GET /server-settings, PUT /server-settings |
GET /server_settings/email |
GET /server-settings/email/settings |
POST /server_settings/email/test |
POST /server-settings/email/test |
POST /server_settings/upload/login, DELETE /server_settings/upload/login |
PUT /server-settings/login-photo, DELETE /server-settings/login-photo |
New routes a v0.20 client may use: GET /sync, GET /jobs, GET /activities/{activity_id}/detail, the health chart routes (GET /health/weight/chart and one for each kind), device management under /profile/devices, blocking under /profile/blocked-users, the email change under /profile/email/change, POST /profile/username/change, POST /profile/delete-account, the server log under /server-settings/logs, and PUT /server-settings/email/settings. The API reference lists them all.
Requests and responses
Status codes
- Writes that only carried a message answer
204with no body: password reset, password change, MFA disable, user approval,PUT /strava/client, the email test, Garmin's MFA code and unlink. - These answer
202with a job instead of finishing in the request:PATCH /activities(bulk edit),DELETE /gears/{gear_id},POST /users/{user_id}/delete,POST /profile/export,POST /profile/import,POST /garmin/link,POST /strava/link,POST /strava/unlinkand the Garmin and Strava gear and health syncs.POST /profile/delete-accountalso answers202, without a job to poll. POST /public/sign-up/requestanswers200instead of201, and the photo uploads answer{"photo_path"}instead of a bare string.
Lists
- One page shape. The gear, health and user lists answered
{records, total, page_number, num_records}; they answer{items, total, page, num_records, next}. The exercise titles, gear components, goals and their results, sessions, API keys, identity providers, identity-provider links andGET /public/idpwere bare arrays and are pages now, with optionalpage_numberandnum_records. - Notifications are a cursor page,
{items, next_cursor, num_records}, and each item has a typed shape bytype.GET /notifications/unread-countanswers{"count"}instead of a bare number.POST /notifications/readmarks the ids it is sent (at most 100), or every unread notification without a body.DELETE /notifications/{notification_id}is new. - Followers. The follower, following and follow-request lists carry the public profile of each user in
users, keyed by user id. - Filters are query parameters with one vocabulary (see Data conventions).
GET /activitiestakesname_containsinstead ofname, andgear_id.GET /gearstakesactiveinstead ofshow_inactive, andgear_typeandnickname_contains.GET /userstakesactive,email_verified,pending_approvalandexternal_authinstead of theshow_*flags, andusernameandusername_contains. The health lists takestart_dateandend_date.GET /activities/feedtakesscope. GET /userswith onlyusers:readanswers422unless it sendsusername(exact) orusername_contains(3 or more characters). The user directory shows less about other users.- Heavy fields are left out of lists. The activity lists leave out
private_notesandimport_info(read the activity by id), and embed the media of the caller's own activities. The sleep list leaves out the stages and sayshas_sleep_stages.
Fields
- Health records name their unit. Weight:
weight,body_fat,body_water,bone_massandmuscle_massareweight_kg,body_fat_percent,body_water_percent,bone_mass_kgandmuscle_mass_kg. Sleep:avg_spo2,highest_spo2andlowest_spo2areavg_spo2_percent,highest_spo2_percentandlowest_spo2_percent. Targets:weight,sleepandfastingareweight_kg,sleep_secondsandfasting_seconds. A request no longer sendssource,user_idor, on an edit,id, and a fasting session no longer takesactual_duration_seconds. - Health instants carry a UTC offset. Every instant in a health request (
fast_start_time,fast_end_time, a poop record'sdate_time, a sleep'ssleep_start_time_gmtandsleep_end_time_gmt, its stage times) must have one;sleep_start_time_localandsleep_end_time_localare wall-clock times without one. - Gear.
initial_kms(kilometres) isinitial_distance(meters), andcreated_atisacquired_on, the acquisition date. A gear request no longer sendsuser_id,strava_gear_idorgarminconnect_gear_id. A component'sexpected_kmsisexpected_usage: meters for gear tracked by distance, seconds for gear tracked by time. OnlyGET /gears/{gear_id}/componentsstill carries a component'scurrent_distanceandcurrent_time. - Activity streams are typed by
stream_type, a string name:stream_waypointshas the shape of its kind. See Activity streams. - Activities gain
mediaandupdated_at. A finished activity job lists the activities it created inactivity_ids. - Profile.
PATCH /profileno longer acceptsusernameoremail, and gainsweight_units. Change the username atPOST /profile/username/changeand the email atPOST /profile/email/change; both need step-up. - Users (administrators).
PATCH /users/{user_id}is a partial edit. It needs the administrator'sstep_upto change the email, access type, active flag, username or email-verified flag, and it answers409instead of activating a user who awaits approval: usePOST /users/{user_id}/approve.POST /userswithout apasswordsends the new user an invitation when email is configured, and is refused withpassword-requiredotherwise; creating an administrator needsstep_up. - Sign-up.
POST /public/sign-up/requesttakes onlyname,username,email,preferred_languageandpassword; the profile fields (birthdate, city, units and the rest) are refused. The password is required there only when email verification is off; with verification on, it is chosen atPOST /public/sign-up/confirm, which takes{"token", "password"}. Both answer{"next_step"}instead ofadmin_approval_required,email_verification_requiredandmessage. See Confirming a link. - Password reset.
POST /public/password-reset/confirmtakespasswordinstead ofnew_password. - MFA.
POST /profile/mfa/enabletakestotp_codeandstep_upinstead ofmfa_codeandcurrent_password, and answers the backup codes. MFA enable, disable and backup-code requests, and starting an identity-provider link, takerevoke_other_sessions(password changes already did). - Server settings.
password_typeis gone. The public settings replaceallowed_redirect_schemeswithallowed_redirect_uris, the exact addresses an SSO sign-in may return to, so a native app can check that its callback is allowed before it opens the browser. The admin settings returntileserver_api_key_setinstead of the key. - Strava.
POST /strava/linktakescode,scopeandstatein the body.PUT /strava/clienttakes astep_upobject next to the client id and secret.
Concurrency
- Reads of a versioned resource carry an
ETag.PUTandPATCHon a versioned resource, andDELETEof an activity, gear, gear component, health record or goal, requireIf-Match. So doPOST /users/{user_id}/delete,POST /identity-providers/{idp_id}/deleteandPOST /health/fasting/{health_fasting_id}/complete. A missingIf-Matchis428and a stale one412. In v0.20 only activities had anETag. See Concurrent edits.
Jobs
- Every
202exceptPOST /profile/delete-accountreturns a job with an id andContent-Location: /jobs/{id}. Read it atGET /jobs/{job_id}and list your jobs atGET /jobs. See Background operations. - Poll the path
Content-Locationnames and wait the seconds inRetry-Afterbetween polls; a finished job sends noRetry-After. The job statuses are renamed:pending→queued,processing→running,completed→succeeded, andfailedstays.completed_atisfinished_at. A client that treats an unknown status as "still running" polls a finished job until it gives up. A bulk import with failed files still endssucceeded; readfiles_failed. - Activity uploads. A user may have at most 10 uploads open at once; the 11th
POST /activities/uploadis409withurn:endurain:error:conflict, and a replay with anIdempotency-Keythat already has a job answers that job even at the limit. An unsupported or mismatched file type is415instead of400. - Garmin link.
POST /garmin/linkanswers202with a job. When the job reportsmfa_required, send the code toPOST /garmin/mfaand keep polling.
Errors and limits
- A request that does not fit the account's state is
409, an unsupported file type is415, and a NUL character or out-of-range value is422. New typed problems includepassword-too-short,password-breached,password-required,api-key-limit,mfa-enrolment-required,precondition-requiredandcomponents-outside-gear-type. See Errors, concurrency and rate limits. - A request under
/auth/or/public/with a body over 64 KiB is413. /openapi.jsonis served only in development and demo installs. Use the published API reference otherwise.
Single sign-on and identity providers
- Mobile SSO needs an exact redirect address listed in
ALLOWED_REDIRECT_URIS. Aredirectthat is not listed exactly (other path, extra query or fragment) is400; the scheme is matched case-insensitively and the rest exactly. A claimedhttpsaddress (Android App Link, iOS Universal Link) can be listed; v0.20 refused everyhttpandhttpsredirect. - Hand-off to the app. For a custom-scheme address, the web page passes the
session_idto the app only after the user confirms it; a claimedhttpsaddress is forwarded at once. The app readssession_id, orerror, from the query of the deep link. A failed sign-in that started from an app now returns to the app witherror(sso_failed,sso_email_missing,sso_email_unverified,sso_auto_create_disabled,sso_link_by_email_disabled,sso_approval_pending,sso_account_disabled) instead of the web login page. - An SSO sign-in is bound to the browser that started it. Open the login in a browser that keeps cookies (system browser, Custom Tabs,
ASWebAuthenticationSession) and finish it there: theendurain_idp_bindingcookie must come back on the callback. Start it on theENDURAIN_HOSTorigin, overhttpsin production and demo. A login started on a LAN address or another host name is refused at the callback with400and "Invalid or expired OAuth state". See OAuth/SSO and PKCE. - Provider API. Creating, editing and deleting a provider needs step-up, and an edit or delete needs
If-Match.jwks_uriis gone, because the signing keys come from the discovery document.client_idis required when creating a provider. Providers are typed (oidcneeds anissuer_urland theopenidscope),samlis refused (existingsamlproviders becameoauth2), and there is one provider per issuer. Aclient_idorclient_secretsent asnullis refused with422instead of clearing the credential.icontakes only a built-in key (authelia,authentik,casdoor,keycloak,pocketid), and an uploaded icon is set atPUT /identity-providers/{idp_id}/icon. Reads gainversion,icon_uploaded,has_linked_users,link_by_emailandsync_email. - Locked fields. The slug,
client_id, provider type, issuer and endpoints cannot change while users are linked:409withurn:endurain:error:identity-provider-locked. - Reserved slugs:
login,link,callback,iconandbackchannel-logout. - Linking by email and email sync are per-provider switches,
link_by_emailandsync_email. Linking by email also requires the Endurain account's own email to be verified. An existing account is not changed before its second factor passes. - Unverified emails. A provider email that is not verified never matches or creates an account. It is refused with
sso_email_unverified, before any account is looked up. v0.20 created an account from it. - Last sign-in method. Unlinking a provider answers
409withurn:endurain:error:last-sign-in-method(it was400) when the account would have no other way to sign in. A disabled provider does not count, and a password counts only when the account's type may sign in with one. - Linking a provider.
POST /profile/identity-providers/{idp_id}/linktakes astep_upbody and an optionalredirect, and answers{"authorization_url"}. With a nativeredirectthat URL is an Endurain address,GET /public/idp/link?ticket=..., for the system browser. The one-time link-token route is removed. See Linking accounts. - Disabling a provider ends the sessions it signed in.
Emails and links
- Links in emails carry the token in the URL fragment (
#token=), so it stays out of logs andRefererheaders: password reset (/reset-password#token=), sign-up confirmation and invitation (/signup/confirm#token=), and email change and its cancellation (/confirm-email-change#token=,/cancel-email-change#token=). The web app still reads?token=on/reset-password, so a reset link sent before the upgrade works. Sign-up verification links moved from/verify-emailto/signup/confirm, so one sent before the upgrade no longer opens; the user asks for a new one. - Email change is a new flow.
POST /profile/email/change(with step-up) emails a link to the new address, andPOST /public/email-change/confirm(204) switches the address when the person presses the button on the page. The old address gets a link to cancel it. See Confirming a link.
Profile export and import
- Export runs as a job.
GET /profile/exportstreamed the archive; nowPOST /profile/exporttakes astep_upbody and answers202with a job, andGET /profile/export/downloadreturns the archive for two hours after the job succeeds.POST /profile/importanswers202with a job instead of201. See Profile export and Background operations. - A profile archive exported by an Endurain version before v0.21.0 cannot be imported. The job fails with
error_code: older_versionand nothing is imported. Export again after the upgrade. - Sleep, steps, water, fasting and bowel movement records are now part of the export and import (v0.20 had only weight and targets).
- An import from a different account is refused (
wrong_account): the archive's username or email must match the importing account's.
Realtime
POST /ws/ticket answers {"ticket"}, needs notifications:read, and the ticket is bound to the session. The socket checks the browser's Origin, limits handshakes, and closes with 4401 when the session ends. An API key cannot open it. See Realtime updates.
Sync
GET /sync is new. It reports what changed in a user's records since a cursor, for clients that keep a local copy. See Keeping a local copy in sync.
Checklist for client developers
- Sign in again, and request the new scope names:
accountinstead ofprofile, kebab-case instead of underscores, andaccount:security,account:exportoraccount:integrationswhere the routes need them. - Treat every id as a UUID string, and drop any code that parses, sorts or compares ids as numbers.
- Read enums (
activity_type,visibility,media_type,stream_type, notificationtype) as strings and prices as decimal strings. - Move every renamed route (see Routes), and send
PATCHwith the id in the path for edits. - Rename the health and gear fields, read lists as
{items, …, next}pages, and send the new filter names. - Send
X-Client-Typeon every/auth/request, drive sign-in bynext_step(includingpassword_change), and treat an unknown step as "update the app". - Send the mobile login PKCE values as form fields,
mfa_challengeinstead ofusernameto/auth/mfa/verify, and exchange the session atPOST /auth/sessions/{session_id}/tokens. - On mobile, send the refresh token in the JSON body of
/auth/refreshand/auth/logout, and store and sendX-Device-Id. - On a
401withsession-ended, sign in again without retrying. Refresh once and replay only oninvalid-token. - Stop sending and reading CSRF tokens. A web client sends
OriginonPOST /auth/refreshandPOST /auth/logout. - Send a
step_upobject on sensitive requests. - Send
If-Matchwith theETagyou read onPUT,PATCHandDELETEof versioned resources, and refetch on412. - Follow
Content-Locationon every202, pollGET /jobs/{job_id}, and map the renamed job statuses (queued,running,succeeded,failed). - Register
com.endurain.endurain:/auth/sso/callbackfor mobile SSO (or ask the operator to allow your address), open the SSO login in a browser that keeps cookies, and handle theerrorcodes on the deep link. - Read email-link tokens from the URL fragment.
- Export profile archives again, because archives from v0.20 cannot be imported.