The Sylo app
A native iOS app (SwiftUI, source in apps/sylo-ios) that signs in to a Sylo
instance, the hosted one or your own, and manages your servers through the same
JSON API the dashboard uses. This page covers what a self-hosted instance
needs for the app to work, and how the app’s sign-in works for anyone reading or
reviewing it.
On the App Store. The app (“Sylo – Server Manager”) is on the App Store. The server side described here is part of Sylo; it does nothing until an app signs in.
What the app covers
Section titled “What the app covers”Everything a server administrator can do in the dashboard, the app can do too, and the app has no “manage this in the web dashboard” links. That covers:
- every module’s settings, including the ones with lists to manage (reaction roles, custom commands, reminders, events, giveaways, applications and their forms, introductions, the economy with its shop, balances, inventories and activity, and the rest);
- moderation (cases, bans, warnings, timeouts, channel locks), tickets, appeals, and the audit log;
- embed messages and the command list per server;
- the server’s general settings, the configuration export, and a member’s data (look up, export, erase);
- Insights, the leaderboard, the roadmap, the changelog, and the account page (connected platforms, signed-in devices, delete account).
The people who run the instance (its operators) get their own screens too, under Settings and only for operator accounts: Health with the database backups (create, download, import, restore, delete) and the dev-log tests, the Bot Personalizer, the stats cache and the roadmap admin. See Health and the dev log (operators).
What stays on the web is only what is not an administrator’s job: the public pages (the web shop, the application forms, event and quote pages) that members open in a browser. The app can copy or open the address of a public page; it never needs the dashboard to finish a task.
The app works against older Sylo servers too: it hides what a server does not offer and never sends a field the server did not send.
What a self-hosted instance needs
Section titled “What a self-hosted instance needs”Nothing new to configure. The app signs in with the dashboard login you already have:
- Discord login:
DISCORD_CLIENT_SECRETand the<DASHBOARD_URL>/auth/discord/callbackredirect, see Dashboard authentication. - Fluxer login:
FLUXER_CLIENT_SECRETand the<DASHBOARD_URL>/auth/fluxer/callbackredirect, see Dashboard login. - Either one, or both. With both, the app’s sign-in sheet shows the usual choice.
The phone has to reach the instance at the address you type into the app, so
DASHBOARD_URL should be that same address (typically the public HTTPS URL
behind your reverse proxy).
Open mode does not work with the app. Without a client secret the dashboard
has no accounts, so there is nobody to sign in as: /api/mobile/info reports
"login": false, the sign-in routes (/auth/mobile/*, /api/mobile/token)
answer 404, and the app says this server has no login.
Open mode is meant for a trusted LAN only and never hands out tokens.
Behind a proxy with its own login
Section titled “Behind a proxy with its own login”If something in front of Sylo asks for its own login (Pangolin, Cloudflare Access, Authelia, nginx basic auth and so on), split the paths:
- The sign-in sheet is a browser. It can show the proxy’s login page and
keeps the proxy’s cookie, so
/auth/*(including/auth/mobile/*) can stay behind the proxy login. - The app’s own requests are not a browser. They carry the app token but no
proxy cookie, so the proxy would answer them with its login page.
/api/mobile/*and/api/v2/*must be reachable without the proxy login. Sylo authenticates those requests itself, with the app token or the dashboard session, and refuses anything without one.
| Path | Proxy login |
|---|---|
/auth/* |
May stay on |
/api/mobile/* |
Bypass |
/api/v2/* |
Bypass |
| Everything else | Up to you |
For example, in Pangolin turn on the resource’s Access Rules and add two
rules with the action Bypass Auth, match type Path, for /api/mobile/*
and /api/v2/*; in Cloudflare Access add a second application for
sylo.example.com/api/mobile and sylo.example.com/api/v2 with a Bypass
policy; in Authelia add rules for ^/api/(mobile|v2)/ with policy: bypass
above the rule that protects the domain; in nginx put auth_basic off; in a
location ~ ^/api/(mobile|v2)/ block.
Only bypass these paths when Sylo’s own login is on (a client secret is set).
In open mode the proxy login is the only thing protecting /api/v2.
How sign-in works
Section titled “How sign-in works”The app uses ASWebAuthenticationSession with the custom URL scheme sylo://
(universal links would need a file on the server’s domain, which a self-hosted
instance cannot provide for the app). It follows the shape of OAuth’s
authorization-code flow with PKCE (RFC 7636, S256 only).
-
The app makes a random
verifier(43 to 128 characters ofA-Z a-z 0-9 . _ ~ -), itschallenge = base64url(sha256(verifier))(43 characters) and a randomstate(8 to 128 of the same characters). -
It opens a browser sheet on
GET /auth/mobile/start?challenge=…&state=…[&platform=discord|fluxer]. Sylo remembers the challenge and state in the browser session for 10 minutes. A missing or malformed value, or aplatformthat is not configured, gives an error page. -
The person signs in through the normal login: straight to that platform’s login when
platformis given or only one is configured, else the login chooser. Someone already signed in in that browser skips this step. -
The login returns to
GET /auth/mobile/confirm: “Sign in to the Sylo app?”, showing the account name and platforms and the address of this server (so a person can notice a server they did not expect), with Allow and Cancel. -
Allow posts the form back (with a per-flow nonce). Sylo creates a one-time code and redirects to
sylo://auth?code=…&state=…&iss=<server>. Cancel goes tosylo://auth?error=access_denied&state=…&iss=<server>. -
The app checks that
stateis the one it sent and thatissis the server it chose (see the issuer), then exchanges the code:POST /api/mobile/tokenContent-Type: application/json{ "code": "…", "verifier": "…", "deviceName": "iPhone" }{"token": "sylo_…","expiresAt": 1799999999999,"account": {"name": "ferdi","avatar": "https://cdn.discordapp.com/avatars/…png?size=…","platforms": ["discord", "fluxer"],"owner": false}}expiresAtis in milliseconds since the epoch.avatarmay benull.owneris true for an account listed inOWNER_IDS/FLUXER_OWNER_IDS.deviceNameis optional (control characters are removed, at most 100 characters,Sylo appwhen empty). Any failure (unknown, used or expired code, wrong verifier, malformed body) is400 { "error": "invalid_grant" }. -
Every API request then sends
Authorization: Bearer sylo_…. -
Signing out in the app calls
DELETE /api/mobile/tokenwith that header, which answers204and revokes the token at once.
The iss parameter
Section titled “The iss parameter”Both app callbacks (sylo://auth here, sylo://connected under
Adding the other login) carry iss, the address of the
server that made them, in the style of RFC 9207. It is the origin of this instance’s
public URL (DASHBOARD_URL, else the address the browser used): scheme, host and port
only, with no path and no trailing slash, for example https://sylo.example.com or
http://192.168.1.20:3000. It is URL-encoded in the callback and is on error callbacks
too.
It exists to stop a mix-up attack: a malicious self-hosted Sylo server could send the
sign-in sheet on to a different Sylo server and then redeem the code that server
issues. The app must therefore compare iss with the origin of the server the person
chose, and reject the callback on a mismatch (do not exchange the code, do not
finish the link). Compare origins, not strings: the host is case-insensitive and a
default port may be left out. The confirmation pages also show the server address, so a
person can notice a server they did not expect.
Two things follow for operators:
- Behind a reverse proxy, set
DASHBOARD_URLto the public address (the same one people type into the app). Without it,issis built from the request, which behind a proxy that ends TLS can behttp://…or an internal name, and the app then rejects its own server. - Separate Sylo instances need distinct origins. Only the origin is compared, so two
instances served from different paths of one host (
https://host/a,https://host/b) are not told apart byiss.
Servers older than this change leave iss out. An app that still supports them may
accept a callback without iss; one that does not can require it. A callback that has
iss must always match. Apps that ignore unknown parameters keep working with newer
servers.
Adding the other login
Section titled “Adding the other login”An account holds one Discord and one Fluxer login. On a Sylo that has both set up
(app-connect in the features), the app can add the one the account
lacks, so a Discord account can also sign in with Fluxer, or the other way round.
Disconnecting needs nothing new: the account page does it.
The login is finished in the app, with its token, not by the browser. That is what keeps someone else’s link from attaching your login to their account.
-
The app asks for a code. It needs its token, and only for a platform the account does not have yet:
POST /api/mobile/connect/fluxerAuthorization: Bearer sylo_…{ "code": "…", "expiresAt": 1799999999999 }400 { "error": "invalid_platform" }for a platform that is unknown or not set up here,409 { "error": "already_connected" }when the account has it. The code names the account and the token that asked. -
The app opens
GET /auth/mobile/connect?code=…in the browser sheet, on the same address. The page asks “Add Fluxer to the Sylo account name?”, says which account that is and shows the address of this server. If the browser is signed in to the dashboard as somebody else, it warns that someone else may have started this. -
Continue leads to the other platform’s login, which is asked to show its consent screen (
prompt=consent), so the person sees which of their accounts there is used. -
The callback links nothing. It keeps the verified login under a result code (120 seconds, single use, stored as a hash, bound to the account and the token from step 1) and ends the sheet at
sylo://connected?platform=fluxer&result=<code>&iss=<server>or, when nothing was kept,
sylo://connected?platform=fluxer&error=<word>&iss=<server>with one ofaccess-denied(cancelled),invalid-response,expired(took more than ten minutes),provider-error,token-revoked(the app was signed out meanwhile),identity-linked(that login already belongs to another account) oralready-linked(the account already has a login on that platform).issis this server’s origin, as in the sign-in: the app must reject a callback whoseissis not the server it chose, before it usesresult. -
The app completes the link with the same token:
POST /api/mobile/connect/completeAuthorization: Bearer sylo_…Content-Type: application/json{ "result": "<code>" }{ "ok": true, "platform": "fluxer", "platforms": ["discord", "fluxer"] }The login is linked only when this token is the one that asked for the code in step 1. Anything else is
400 { "error": "invalid_result" }(unknown, used, expired, or made for another token or account), and the code is used up by the attempt.409withidentity_linkedoralready_linkedwhen the login or the platform was taken in the meantime;401when the token is no longer valid.
The browser is not signed in to Sylo at any point: nothing here starts, replaces or extends a web session.
For app developers. In the case this design exists for (someone else’s link opened in
the person’s ordinary browser), the sylo://connected?…&result=… redirect goes through
the operating system’s URL-scheme dispatcher, and an app on the device that also claims
sylo:// could receive it. The server cannot prevent that, because the one who started
the flow is the attacker. So the app must act only on the callback that comes back from its
own ASWebAuthenticationSession (the one it opened in step 2), and must ignore a
sylo://connected URL that arrives through the normal URL handler. Without the matching
token a result code is useless to anyone else anyway.
Endpoints
Section titled “Endpoints”| Method and path | Auth | Answer |
|---|---|---|
GET /api/mobile/info |
None | What this server is (below) |
GET /auth/mobile/start |
None (browser) | Redirect to the login, or to the confirmation page |
GET /auth/mobile/confirm |
Browser session | The confirmation page |
POST /auth/mobile/confirm |
Browser session + nonce | Redirect to sylo://auth?code=…&state=… |
POST /api/mobile/token |
Code + verifier | { token, expiresAt, account }, or 400 invalid_grant |
DELETE /api/mobile/token |
Bearer token | 204, or 401 without a valid token |
POST /api/mobile/connect/:platform |
Bearer token | { code, expiresAt }: a one-time code to add that platform’s login (Adding the other login); 400, 401, 403 or 409 |
GET /auth/mobile/connect?code=… |
None (browser) | The confirmation page; the link is used up when it is opened |
POST /api/mobile/connect/complete |
Bearer token | { ok, platform, platforms }: links the login the sheet ended with, for the token that began the flow only; 400 invalid_result, 401, 403 or 409 |
GET /auth/mobile/connect/continue?nonce=… |
Browser session + nonce | Redirect to the other platform’s login |
/api/v2/* |
Bearer token | The dashboard’s JSON API |
GET /api/v2/changelog?limit=N |
Bearer token or session | { version, releases: [{ version, date, url, sections: [{ title, kind, items: [{ scope, text, refs }] }] }] }, newest first; the same release notes as the dashboard’s What’s new page |
GET /api/v2/guilds/:id/members?q= |
Bearer token or session, Manage Server | { members: [{ id, name, username }] }: the server’s members by name (those Sylo has cached) or one pasted id (looked up live), never a bot, at most 25. 100 searches per minute per account and server |
GET /api/v2/guilds/:id/health |
Bearer token, server admin | The permission and role-hierarchy health check of one server (below) |
GET /api/mobile/info is public. The app calls it when you type a server
address, to tell whether the address is a Sylo server and whether it can sign
in there:
| Field | Meaning |
|---|---|
name |
Always "Sylo" |
version |
The Sylo version, for example "4.0.0" |
apiVersion |
The app API version, currently 1 |
login |
Whether sign-in is available (false in open mode) |
loginProviders |
The configured logins, for example ["discord", "fluxer"]; empty when login is false |
platforms |
The platforms the bot runs on, for example ["discord"] |
features |
What this version’s app API supports, so the app can hide what an older Sylo lacks. Today: app-login, live-access, changelog, collectibles, welcome-trigger, member-search, access-levels, health, app-connect, setup-wizard, config-history, inbox-search, config-import, duplicate, message-templates and message-move, plus moderator-view, update-notice and public-page-look from Sylo 5.3, plus push and push-pigeon when this instance can send notifications. See the list below |
The feature strings:
app-login: the app sign-in above.live-access: server access is checked live through the bot on every request.changelog:GET /api/v2/changelog.collectibles: the Economy shop’s collectible items, their picture upload and the inventory.welcome-trigger: the Welcome module’striggersetting (a member joins, or first gets a role).member-search:GET /api/v2/guilds/:id/members?q=.access-levels: the dashboard access levels (View, Inbox, Edit).health:GET /api/v2/guilds/:id/health, the health check.setup-wizard:GET /api/v2/guilds/:id/setup/suggestandPOST /api/v2/guilds/:id/setup/apply.config-history: the before and after values of audit entries, and the undo:GET /api/v2/guilds/:id/audit/:entryId/change: the audit list only flags an entry withhasChange(andrevertsId, the entry an undo undid). This call gives the values:beforeandafter(secrets masked),names(channel, role and member names for the ids in them),kind("module","settings"ornull) andundo.undohasavailable,reasonwhen it is not,state(clean: nothing changed since;changed: changed again since;reverted: already back to the earlier values),laterChanges(the keys changed again),token,notRestoredanddroppedSecrets. A change too large to keep answerstooLarge: trueand anundowithavailable: false. An entry without a saved change is a404.POST /api/v2/guilds/:id/audit/:entryId/undo: restores the earlier values and answers{ ok, adjusted, notRestored }. When the settings were changed again since the entry it answers409withcode: "changed-since",laterChangesand atokeninstead, and restores nothing. The app shows what would be lost, and if the person confirms it sends the same request again withconfirm: trueand thattoken. The token names the saved values the person saw, so if they changed again meanwhile the answer is a new409. Whenstateischanged,GET …/changealready gives thattoken(otherwise it isnull), so the app can ask first.
inbox-search:GET /api/v2/guilds/:id/search/inbox.config-import:POST /api/v2/guilds/:id/import/previewandPOST /api/v2/guilds/:id/import/apply.duplicate: theduplicateroutes for reminders, embed messages, reaction-role sets, custom commands and shop items.message-templates: the built-in message templates and the raw message JSON import and export.message-move: when the channel of a posted embed message, the Welcome channel message or a role panel changes and is published, the server posts a fresh message in the new channel, stores it and then deletes the old one, so the app must not unpublish first. Other bot posts (verification, honeypot traps, applications and so on) are not covered. A publish that loses a race with another publish of the same embed message answers409with the current record.moderator-view(Sylo 5.3): the web dashboard gives a person whose level in a server isinboxa focused view: the server opens on the inbox, and the navigation lists only the moderation tools (Tickets, Appeals, Applications, Suggestions, Moderation hub, Member data; only the inboxes that are switched on), with a “Show everything” switch for the full, still locked, navigation. Nothing changes on the server side: the level is theaccessof eachGET /api/v2/guildsentry (andlevelofGET /api/v2/guilds/:id/access). The app can follow the same rules for that level and keeps the full read-only app forview.update-notice(Sylo 5.3): the operators’ update notice:GET /api/v2/update, and with Wise Wren set upPOST /api/v2/update/wren/approveandGET /api/v2/update/wren/runs/:id. Operators only.public-page-look(Sylo 5.3): the server’s look on its public pages:GETandPOST /api/v2/guilds/:id/public-page-look, the background upload and the invite-background check.app-connect: adding the other login. Only where sign-in is on and both Discord and Fluxer logins are set up.push,push-pigeon: this instance can send notifications to signed-in apps.
An older Sylo without this endpoint answers 404, and the app says the server
is too old for it. A Sylo that has the endpoint but lacks a string does not have
that feature: the app hides the control.
Health check
Section titled “Health check”GET /api/v2/guilds/:id/health tells a server admin what Sylo cannot do in the places its modules are
set up to use: a channel it cannot post in, a role it cannot give because Sylo’s role is not above it,
a permission an action needs. Only the modules that are switched on are checked. The answer is cached for
a minute per server and is dropped when a setting is saved; ?refresh=1 checks again at once (6 per minute).
{ "guildId": "…", "available": true, "platform": "discord", "checkedAt": 1760000000000, "summary": { "errors": 1, "warnings": 0 }, "checks": [{ "module": "verification", "moduleName": "Verification", "severity": "error", "code": "role-above", "kind": "role-hierarchy", "message": "Sylo can't give Verified: Sylo's role is not above it.", "fix": "In the server's role settings, move Sylo's role above Verified.", "href": "/v2/guilds/…/m/verification", "targetKind": "role", "targetId": "…", "targetName": "Verified" }], "targets": { "roles": { "blockedAll": null, "blocked": { "<roleId>": "above | managed" } }, "channels": { "blocked": { "<channelId>": ["View Channel", "Send Messages"] }, "noEmbed": ["<channelId>"] } }}severity is error when a module cannot do that part of its job and warning when it still works.
targets lists only the roles Sylo cannot give and the channels it cannot send in (blocked), and the
channels where it can send but lacks Embed Links (noEmbed, which matters only to a module that sends an
embed there), for a picker to warn about a choice that is not saved yet. A permission the platform does not
have (Fluxer has no thread permissions) is never reported. The same checks come with the overview, in attention.health.
On a token request, “not signed in” and “not allowed” are JSON, never a redirect or an HTML page:
| Status | Body |
|---|---|
401 |
{ "error": "Not signed in, or the token is no longer valid." } |
403 |
{ "error": "You do not manage this server." } |
403 |
{ "error": "Your dashboard access in this server is View only, so you can't do this.", "access": "view", "required": "edit" } |
403 |
{ "error": "Restricted to Sylo's operators." } |
The usual per-IP rate limits apply. On top of them, per minute: 60 calls to
/api/mobile/info, 30 to the /auth/mobile pages and 20 code exchanges. Adding a login
allows 10 codes and 10 completions per token and 10 visits to its two pages per client.
Actions that post to the platform (test messages, publishing a message or role
menu, locking or unlocking every channel) share a limit of 10 per minute per
server and account, answered with 429 and an { "error" }.
Public page look
Section titled “Public page look”public-page-look in features. A server may give the pages its members open without the dashboard (the
application form, the ban appeal, the quote and leaderboard pages and the web shop) its own accent colour and a
background. That is all it can change: the layout, the type, the components, the light and dark themes and the
“Powered by Sylo” link at the bottom of every public page stay Sylo’s, and the dashboard and the app are never
restyled. The form always sits on a semi-opaque card over a dim overlay (opaque when the visitor asks for reduced
transparency). Every route here needs the edit level, the read too (a lower level gets the usual 403).
| Call | What it does |
|---|---|
GET /api/v2/guilds/:id/public-page-look |
The choice and what it comes to (below) |
POST /api/v2/guilds/:id/public-page-look |
Saves { "accent": "#5865f2" or "", "background": "none", "upload" or "discord-splash" } and answers like the GET |
POST /api/v2/guilds/:id/public-page-look/image |
Uploads the background: a multipart body with the field file (PNG, JPEG or WebP, at most 2 MB, at most 16 megapixels). Sylo stores a new WebP of at most 1920 pixels, so metadata is gone. Answers like the GET. It does not change the choice: save "background": "upload" after it |
POST /api/v2/guilds/:id/public-page-look/image/delete |
Deletes the uploaded picture (a choice of upload falls back to none) and answers like the GET |
POST /api/v2/guilds/:id/public-page-look/splash/refresh |
Checks the invite background against the platform now and answers like the GET. Without it Sylo checks once a day, when a page that uses it is opened |
The answer has accent and background (what was saved), platform, upload (null or { bytes, url, updatedAt }),
splash (available: the server has an invite background on the platform, Discord and Fluxer both have one;
copied: null or { url, checkedAt, updatedAt }, Sylo’s own copy), limits and sylo (Sylo’s accent per theme)
backgrounds (the three values the app may send) and effective: accent (the colour really used for fills and
borders, per theme: dark and light), accentText (the colour used for text, per theme: the accent, or the same hue
lightened or darkened to reach 4.5:1), contrast (the ratio of the accent to the card per theme and whether it reaches
the 3:1 Sylo asks for), fallback (the themes where it does not and Sylo’s own colour is used instead), note (the
sentence to show when fallback is not empty, else null), backgroundUrl (the picture of the chosen background,
or null) and css (the path of the style sheet public pages load, or null when the server chose nothing).
A 400 for a colour that is not #rgb or #rrggbb, for upload with no picture or for discord-splash
when the server has none; 502 when the invite background could not be downloaded. The urls are paths on the
Sylo server itself (the app prefixes the server address); the pictures are never loaded from the platform’s CDN.
Tokens and signed-in devices
Section titled “Tokens and signed-in devices”- A token is
sylo_followed by 32 random bytes (base64url). The prefix makes a leaked token easy to find in a scan. - Lifetime 90 days, sliding. Each use moves the expiry 90 days forward (written at most once an hour). A token unused for 90 days stops working and is purged with the session sweep.
- Only a SHA-256 hash is stored, with the account it belongs to, the device name, when it was created and last used, and its expiry. A copy of the database cannot be used to act as anyone.
- Signed-in devices. The account page (Account in the dashboard,
/v2/account) lists each device with its name and last use, and a Revoke button. - A token stops working, at once, when:
- the app signs out (
DELETE /api/mobile/token), - the device is revoked on the account page,
- the account is deleted (Settings → Delete Account in the app, or the
account page on the web,
POST /api/v2/account/deletewith{ "confirm": true }): every token of the account goes with it, - a sign-in (Discord or Fluxer) is disconnected from the account: this revokes all of the account’s app tokens, and the app has to sign in again,
- it has not been used for 90 days,
- the account signs in on a 21st device: an account keeps at most 20, and the least recently used one is signed out.
- the app signs out (
Device names are shown as sent, minus control and invisible formatting characters, cut to 100 characters.
Token lookups are not cached, so a revocation counts on the next request.
Permissions
Section titled “Permissions”The app has exactly the rights the web dashboard gives the same person. The one difference is how server access is checked:
- Both use the server list stored at login. The bot keeps it current: when it sees someone gain or lose Manage Server or Administrator, or become the owner, that server is added to or removed from their list. Neither the dashboard nor the app sends anyone through the platform login again to refresh it.
- The web dashboard trusts that list for 10 minutes after login, then checks live through the bot, like the app.
- For app requests Sylo checks live, through the bot, on every request: the person must own the server, have Manage Server or Administrator there, or hold one of its dashboard access roles (below). Someone who loses those rights loses access from the app at once. The bot has to be in the server. The live check only runs for a server that was in the stored list at sign-in, or that has access roles set, so a token cannot make the bot look people up in every server it is in. This covers the ticket pages too.
- The server list (
GET /api/v2/guilds) is the stored list filtered by the same live check, plus the servers where the bot sees you holding an access role. Each entry carriesaccess:"edit","inbox"or"view". A server where you newly gained Manage Server shows up after the next sign-in. - Owner-only modules and bot-wide pages stay limited to
OWNER_IDS/FLUXER_OWNER_IDS, the same as in the browser.
Access levels
Section titled “Access levels”Every per-server route needs one of three levels (access-levels in features):
| Level | Who | May |
|---|---|---|
edit |
The owner, Manage Server, Administrator, the bot-master roles | Everything, as before |
inbox |
The server’s Inbox roles, and ticket staff roles for tickets | Read everything, including what the inboxes contain; reply to and close tickets, decide appeals, applications and suggestions |
view |
The server’s View roles | Read the pages, lists and settings; change nothing |
A request above the person’s level gets 403 with access (their level) and
required (the level the route needs).
- What the inboxes contain needs
inbox:GET .../tickets/:id(and its/messagesand/transcript),GET .../applications/submissions/:idandGET .../applications/export. Withview, the lists still answer, but without that content, and withcontentHidden: true: the tickets’previewandpreviewKind, the appeals’answersanddecisionReason, the applications’reason, and the author of an anonymous suggestion are empty. - Settings that hold a secret show it only with
edit: GitHub webhook secrets and addresses arenull, and RSS feed URLs show only their origin. The configuration download (GET .../export) and the insights refresh neededit. - Deciding an application checks the person deciding: they must be able to hand
out every role the decision gives (as when saving the form), no such role may
give more dashboard access than their own, and nobody decides their own
application. With
inbox, accepting an appeal (which lifts the ban) also needs Ban Members. GET /api/v2/guilds/:id/accessanswers{ level, editRoleIds, inboxRoleIds, viewRoleIds, canChangeEditRoles }.POSTto the same path with any ofeditRoleIds,inboxRoleIdsandviewRoleIdschanges them; it needsedit, and changingeditRoleIds(the bot-master roles) also needs Manage Server, as on the settings page.- Ticket notifications go to
inboxandedit(and ticket staff) only. - Publishing a message (
POST .../messages/:idwithaction: "publish") pings a role in the text only when the person could ping it themselves: the owner, Manage Server or Mention Everyone, or a role that is mentionable. The answer carriesrolesSilent, the names of roles in the text that were shown but not pinged (an empty list when none); the app can show it as a notice. Publishing a message with role buttons or menus needs the right to hand out every one of those roles, and answers403otherwise.
Notifications
Section titled “Notifications”The app can tell a server’s staff about new ticket messages: a notification when a member opens a ticket, and one for each new message a member writes in an open ticket. Staff and system messages never notify. It shows the server’s name, the member and the first 180 characters of the message; iOS groups a ticket’s notifications, and a tap opens the conversation.
- Who gets one: every signed-in device with notifications turned on whose account may see that server’s tickets at that moment (the same live check as for the app’s requests, or a tickets staff role), unless that server is muted in the app’s settings.
- Turning it on: the app asks the first time you open a server’s Tickets tab; the app’s settings have the switch and one per server. Signing out or revoking the device stops its notifications at once.
How they reach the phone
Section titled “How they reach the phone”An instance has three ways to notify a device, and picks one per device by what that device’s app sign-in holds. A newer app uses Postal Pigeon when this instance offers it; an older app build keeps using the relay or the direct way, so nobody loses notifications when an instance turns Pigeon on.
- Postal Pigeon (
PIGEON_URL): Postal Pigeon is the Hedgerow push relay,https://pigeon.hedgerow.tools./api/mobile/infonames it (pigeon) and lists the featurepush-pigeon. The app registers its device with Pigeon and gives your instance only a handle (hrh_…), so your instance never sees the device’s push token. A notification then carries no text: your instance asks Pigeon to push to the handle, with a random reference and a collapse key (below), and Pigeon and Apple deliver a generic notification. That is all your instance gives Pigeon about a notification. The app’s notification extension asks your instance for the text with that reference (GET /api/mobile/push/events/:ref), so the server name, the member’s name and the message never go through Pigeon or Apple. The app only uses the official Pigeon; an instance that names another gets no notifications from it. Your instance registers itself with Pigeon when it starts, or else the first time it sends (a small proof of work, about a second, then a credential kept in its settings, sealed with a key derived fromSESSION_SECRET), and only makes outgoing HTTPS requests. While it sends, it logs problems with Pigeon at debug level only, because the dev-log notifications go through Pigeon too.- Pigeon allows a device 6 notifications an hour, 3 at once. Your instance keeps
to the same budget; a notification beyond it is dropped (the app lists the
tickets when it is opened). Notifications for one ticket replace each other
on the phone: the collapse key that does this is an HMAC-SHA256 of the
sign-in and the ticket (or the dev log), with a key derived from
SESSION_SECRETfor this purpose alone. Pigeon sees an opaque value that cannot be traced to a server or a ticket without that secret, and that is different for each device. - A device Pigeon has not yet accepted a push for is sent to slowly (one a minute across all such devices, 3 an hour for one), so a made-up handle cannot use up the instance’s allowance for unknown handles at Pigeon.
- The text is kept for two hours (Apple stops trying after one) under the
reference, and is only given to the app sign-in it was made for, only while
that account may still see the ticket (operators only, for the dev log).
Anything else, a reference that is unknown, expired or someone else’s,
is a
404.
- Pigeon allows a device 6 notifications an hour, 3 at once. Your instance keeps
to the same budget; a notification beyond it is dropped (the app lists the
tickets when it is opened). Notifications for one ticket replace each other
on the phone: the collapse key that does this is an HMAC-SHA256 of the
sign-in and the ticket (or the dev log), with a key derived from
- Off: leave
PIGEON_URLunset or empty. Nothing changes for the other two.
The two older ways, for app builds that do not know Pigeon. Apple only accepts notifications for the Sylo app from whoever holds the app’s push key, so a self-hosted instance cannot send them to Apple itself. It sends them through the hosted Sylo instead:
- Self-hosted (the default):
/api/mobile/infonames the relay (pushRelay, fromPUSH_RELAY_URL, defaulthttps://app.sylobot.com). When notifications are turned on, the app registers the device with that relay itself and gives your instance only the relay token it got back, so your instance never sees the device’s push token. Each notification goes from your instance to the relay, which passes it to Apple and keeps no copy of its text. The app only uses the hosted relay; an instance that names another one gets no notifications. Your instance only makes outgoing HTTPS requests; nothing needs to reach it from outside, and a login proxy in front of it needs no new rule. - Off: set
PUSH_RELAY_URLto an empty value./api/mobile/infothen leaves outpush(which is what the older apps look for) and they say notifications aren’t available. WithPIGEON_URLset, apps that know Pigeon still get notifications. - The hosted Sylo holds the key (
APNS_KEY_ID,APNS_TEAM_ID,APNS_PRIVATE_KEY,APNS_TOPIC) and talks to Apple directly.
The relay only sends ticket and dev-log notifications in a fixed shape, at most 60 an hour for one device (across all its registrations, at most 10), and forgets a registration when the app turns notifications off, when Apple reports the device gone, or after 90 days without use.
Endpoints
Section titled “Endpoints”| Method and path | Auth | Answer |
|---|---|---|
POST /api/mobile/push |
Bearer token | { pigeonHandle, environment } (Pigeon), { relayToken, environment } (relay) or { deviceToken, environment } (direct) → { ok: true }; 400 invalid_push_token, or relay_token_required / device_token_required / pigeon_handle_required for the kind this instance does not take; 503 when this instance can’t send |
GET /api/mobile/push/events/:ref |
Bearer token | The text of a Pigeon notification: { title, subtitle?, body, threadId, kind, data }, no server address, Cache-Control: no-store. 404 for an unknown, expired or someone else’s reference, or a ticket the account may no longer see. At most 30 a minute per sign-in |
GET /api/mobile/push |
Bearer token | { enabled, mutedServers }, plus devLog for an operator |
PUT /api/mobile/push/dev-log |
Bearer token, operators only | { level: "off" | "errors" | "warnings" } → { devLog } |
PUT /api/mobile/push/servers/:guildId |
Bearer token | { muted } → { mutedServers } |
DELETE /api/mobile/push |
Bearer token | 204; notifications off for this device |
POST /api/push-relay/v1/register |
None (called by the app) | { deviceToken, environment, instance } → { relayToken }; only on an instance with the APNs key |
POST /api/push-relay/v1/send, /unregister |
Relay token | Called by the instance; only on an instance with the APNs key |
Health and the dev log (operators)
Section titled “Health and the dev log (operators)”The people who run an instance, its operators (OWNER_IDS and
FLUXER_OWNER_IDS), get more in the app, in an Operator section of Settings.
Someone who only has Manage Server never does: the app hides it (it reads
operator from GET /api/v2/account again whenever the sign-in changes), and
the server answers 403 to anyone else. An app token works on these routes when
its account is an operator.
- Health: whether the bot is up, its version, uptime, gateway ping, servers and members, the database, and the dev log, with a test message and a test error for the dev-log channel.
- Backups, from Health: create a backup, download one (it opens in Quick Look
and the share sheet, and the temporary file is deleted), delete one, restore
one, or import a file. Delete, restore and import ask for a typed word. A
restore replaces the live database with the backup and restarts the bot, so
every server’s data goes back to that snapshot, and the app is signed out when
the backup is older than its sign-in. The app does not trust the first answer from
GET /api/v2/healthafter a restore, because the old process keeps answering until the restore is done (and for good if the snapshot of the current database fails): it says the restore is done only after a restart is seen (a loweruptime, or a failed poll when there is no uptime), and otherwise says it could not confirm it. An import is stored as a snapshot only. The import is sent as rawapplication/octet-stream(a JSON body is cut at 256 kB) of up to 128 MB, read from the file as it goes. - Bot Personalizer: the bot’s name and pictures, its presence, and the announcement everyone sees.
- Stats cache: the game-stats lookups every server shares (read only).
- Roadmap admin: review suggestions, post, move a post to another stage, edit, delete.
- The dev log: Sylo’s own errors and warnings, stored in the database for
30 days (the newest 500). It works with or without a dev-log channel
(
DEV_LOG_CHANNEL_ID); the channel still gets errors only. - Dev-log notifications: each device chooses Off, Errors, or Errors and Warnings in the notification settings (Errors to begin with). A notification names the instance, the level and where in Sylo it happened, and a tap opens Health. The same message is sent at most once every 5 minutes.
| Method and path | Auth | Answer |
|---|---|---|
GET /api/v2/health |
Operators only | The Health report |
GET /api/v2/dev-log?level=error&limit=100 |
Operators only | { entries: [{ id, level, scope, message, at }] }, newest first |
POST /api/v2/health/dev-log-test |
Operators only | Posts a test message to the dev-log channel; { ok } or { ok: false, error } |
POST /api/v2/health/dev-log-error-test |
Operators only | Logs a real error to test the pipeline; { ok } |
POST /api/v2/health/backups |
Operators only | Takes a backup; { name } |
GET /api/v2/health/backups/:name |
Operators only | The backup file, as a download |
POST /api/v2/health/backups/:name/delete, /restore |
Operators only | { ok } (a restore then restarts the bot). /restore takes an optional { confirm: <name> }, which must match when sent (Sylo 5.3). From Sylo 5.3, an uploaded (sylo-imported-*) dump on Postgres needs { confirm: <name>, acknowledgeSql: true } (its SQL runs with the rights of the database role), else 400 |
POST /api/v2/health/backups/import |
Operators only | A raw body (application/octet-stream, up to 128 MB); { name } |
GET /api/v2/personalizer, /personalizer/presence |
Operators only | The bot; the presence and its choices |
POST /api/v2/personalizer/identity, /presence, /announcement, /announcement/clear |
Operators only | Bot-wide settings |
GET /api/v2/stats |
Operators only | { rows, ttlMinutes }, the newest 50 cached game-stats lookups |
GET /api/v2/roadmap/admin and POST /api/v2/roadmap/admin[/:id/approve, reject, status, edit, delete] |
Operators only | The roadmap review board |
GET /api/v2/account |
Bearer token or session | Includes operator: true for an operator |
Update notice (operators)
Section titled “Update notice (operators)”Operators also get the update notice (feature update-notice): whether a newer Sylo release is out, what
is in it, and, when the instance runs Wise Wren, an Update
now button. It is the same data as the dashboard’s Health page. Everything is operator-only: a server
admin who is not an operator gets 403, a request without a sign-in 401. The routes are listed in the
table below. Writes are rate limited (5 approvals a minute, 6 re-checks a minute) and answer
429 { error } above that.
GET /api/v2/update answers (add ?refresh=1 to check GitHub again now):
{ "enabled": true, "current": "5.2.0", "latest": "5.3.0", "available": true, "checkedAt": "2026-11-20T10:00:00.000Z", "checkFailed": false, "releaseUrl": "https://github.com/Ferdinand99/Sylo/releases/tag/v5.3.0", "publishedAt": "2026-11-20T09:00:00Z", "notes": { "version": "5.3.0", "date": "2026-11-20", "url": null, "sections": [ { "title": "New", "kind": "features", "items": [{ "scope": "dashboard", "text": "Inline markdown, https links only", "refs": [{ "label": "#370", "url": "https://github.com/..." }] }] } ] }, "notesText": null, "command": "docker compose pull && docker compose up -d", "wren": null}enabledis false when the instance runs withUPDATE_CHECK=off: there is nothing else to show then.availableis true whenlatestis newer thancurrent.checkFailedis true when the last look at GitHub failed (latestthen still holds an earlier answer, if there was one).notesandnotesTextare only set whileavailableis true.noteshas the same sections asGET /api/v2/changelog(items[].textis inline markdown withhttpslinks only, to render as text, never as HTML). Release notes that are not in that format come asnotesText, plain text.wrenisnullwhen Wise Wren is not set up. Otherwise it hasconfigured,error(null, or{ code, message }when Wise Wren could not be asked or does not accept Sylo’s token),openMode(the dashboard has no login, so Update now is off unless the operator allowed it),target({ name, server, status, installedVersion, latestVersion, mode, lastCheckedAt }ornull),updateSeen(Wise Wren sees an update),canApprove,whyNot(the reason when it cannot, in words), andlatestRun(the run Sylo last approved, as below, ornull; Sylo remembers it across its own restart). WhilelatestRunis notfinished,canApproveis false and the page or app should follow that run. It never has Wise Wren’s address, the token or the version key.
POST /api/v2/update/wren/approve (no body) asks Wise Wren to update Sylo now and answers
{ runId, status, from }, where from is the version it started from. It approves exactly the version Wise
Wren shows. Errors are { error, code }: 404 (wren_off) when Wise Wren is not set up; 409 when there is
nothing to approve (not_approvable), when Wise Wren refuses (wren_refused, with Wise Wren’s own message:
the version changed, a run is already going, the agent would refuse it), or in open mode (open_mode);
429; and 502 (wren_unreachable, wren_unauthorized, wren_forbidden, wren_server, wren_invalid)
when Wise Wren cannot be reached or does not accept Sylo’s token. These are never 401 or 403, which stay
for the operator’s own sign-in.
GET /api/v2/update/wren/runs/:id answers { run }, where run is
{ id, status, finished, ok, detail, version, createdAt, startedAt, finishedAt, steps: [{ step, status, durationMs }] }
(status: queued, running, succeeded, rolled_back, failed, rollback_failed, refused,
cancelled, lapsed; finished is true for all but the first two). A run that is not the Sylo target’s
is refused (404, or 502 wren_forbidden from a token limited to one target). Poll it every few seconds, up to
60 requests a minute.
Sylo restarts during an update, so these requests fail for a while (a dropped connection, or 502/503
from a reverse proxy, without a code). The app keeps polling; it is done when the run is finished, or
when GET /api/v2/update (or GET /api/mobile/info) reports a current / version other than from.
| Method and path | Auth | Answer |
|---|---|---|
GET /api/v2/update[?refresh=1] |
Operators only | The update notice above |
POST /api/v2/update/wren/approve |
Operators only | { runId, status, from } |
GET /api/v2/update/wren/runs/:id |
Operators only | { run } |
Security notes
Section titled “Security notes”- PKCE S256 only. The code is bound to the challenge from the start of the flow; without the matching verifier it is worthless.
- Codes are single use and live 60 seconds. Only their hash is stored, and a code is deleted on the first attempt to redeem it, right or wrong, so it cannot be guessed at or replayed.
- The confirmation page stops login CSRF. Without it, someone could send you
a link that signs in as you in your browser and delivers the code to an app on
their side. Allow is a POST with a per-flow nonce, and the app rejects a
callback whose
stateit did not send. - Adding a login is finished by the app, not by the browser. The link that opens the
sheet is made for one account by one app token, so anyone can make one for their own
account and send it to someone else. If the browser’s login were linked on the spot,
that person’s Discord or Fluxer login (and the servers they manage, and operator
rights if they have them) would end up on the attacker’s account. So the callback
links nothing: it keeps the verified login under a result code bound to the account and
token of the connect code, and
sylo://connected?result=…opens on the device of whoever is in the browser. Only the app holding that very token can complete the link; the victim’s own app has another token and is refused. The confirmation page names the account and warns when the browser is signed in as somebody else, as defence in depth. - The codes. Connect code and result code are 256 random bits each, stored only as a SHA-256 hash, deleted in the statement that reads them (so they work once, also under concurrency), and swept with expired tokens; a connect code lives 60 seconds, a result code 120. One live connect code per account. Both stop working when the token is signed out or revoked (checked when the sheet opens, at the callback and at completion), and they are deleted with the account.
- No session, no open redirect. The browser is never signed in or given a session; the
only places it is sent are the platform’s own login and
sylo://connected, with a platform, result and error word that Sylo chose, never one from the request. One login per platform and account is a database rule (a unique index), so two completions at the same moment cannot give an account two logins; the loser gets409. - Tokens only work on
/api/paths. The HTML dashboard stays cookie-only, and a request that presents a token is judged by the token alone (a bad token never falls back to a cookie). - No CSRF token for bearer requests. CSRF works because a browser attaches
cookies to a cross-site request by itself. It never attaches an
Authorizationheader by itself: a page would have to set it, which needs a CORS preflight, and Sylo answers no preflight and sends no CORS headers. A bearer request therefore cannot be forged from another site.