Synology NAS API

Create a saved HTTP or HTTPS connection, choose Protocol → Application → Synology DSM, then choose Synology NAS API in its access settings. Opening the connection embeds the API view in its session tab, without a second enclosing dialog or close button. File Station is its file-management section; the other tabs expose supported NAS administration. The session owns its NAS client: two open NAS tabs do not replace one another. The saved target is fixed for that session; edit the connection to change host, port, or transport.

The standalone Synology NAS API window also remains available: enter the NAS hostname, DSM port, username and password, then choose Connect. File Station opens at the shared-folder list; open a share to manage files. Administration tabs use the same authenticated session when your account has permission.

Sign in and two-factor authentication

HTTPS is enabled by default on port 5001 and verifies the server certificate. Use the hostname covered by the certificate and a trusted certificate chain. Certificate errors are not bypassed. Explicitly choosing HTTP leaves the port unchanged and sends credentials without TLS encryption.

QuickConnect NAS aliases, such as your-nas.quickconnect.to, are resolved anonymously before sign-in. The resolver only selects an admitted same-NAS HTTPS endpoint after identity and API checks; it does not navigate the DSM website or reuse its cookies. Even an HTTP QuickConnect landing alias resolves through verified HTTPS. Discovery and any bounded relay setup use the same selected app-wide route as the later API session. A failed resolution never sends credentials to the provider or falls back to an unrelated endpoint. See native API resolution and session status for the bounds and anonymous gateway fallback.

On DSM 7 the app signs in the way DSM’s own sign-in page does: it completes DSM’s secure login handshake and signs the session’s administration requests. DSM gives a session opened without the handshake, for example over QuickConnect or a remote address, only limited API access, so even an administrator can find data marked Session restricted. If the NAS doesn’t offer the handshake (DSM 6 and older DSM 7 releases) or doesn’t complete it, sign-in continues without it and the session panel says so. See secure login handshake.

DSM has no resumable sign-in, so each attempt, including each code you submit, is a complete new sign-in with a fresh handshake. DSM’s answer decides what happens next:

One-time codes are cleared after every attempt and never saved. Cancel sign-in clears the pending password and code. A saved connection can also answer DSM’s code request itself from a saved authenticator; see Automatic one-time codes. The sign-in never enrolls authenticators or generates website recovery codes.

Of DSM’s second factors, the API can complete only one-time codes. Approve sign-in (Secure SignIn push), security keys and passkeys can’t complete an API sign-in. After DSM asks for a code or refuses the method, the app asks DSM once which sign-in methods the account has and lists them in the dialog as One-time code, Secure SignIn approval or Security key. If the account can also use a code, enter it; otherwise use the DSM website view, which hands those steps to you on DSM’s own page (see Two-factor and Secure SignIn steps). Approving a sign-in in a browser doesn’t authorize the API session. When DSM doesn’t report the methods, the dialog shows the general guidance. See Synology’s DSM login API guide and two-factor authentication documentation.

Automatic one-time codes

A saved connection can generate the code DSM asks for from the authenticator enrolled for the DSM account. Choose it in the connection’s Synology access settings, under Two-factor authentication — automatic one-time codes. Choosing an authenticator turns automatic codes on; there is no separate switch. None — enter codes manually turns them off. The standalone Synology NAS API window has no saved authenticator and always asks for codes.

• Local credentials. Choose an authenticator already listed under Protocol → Recovery → 2FA / TOTP, or choose Add authenticator secret. Enter the Base32 secret DSM showed when you set up your authenticator app (at least 16 characters; spaces and dashes are allowed), or paste its otpauth://totp/ link, then choose Save authenticator. Advanced settings apply only to a Base32 secret; DSM uses 6 digits, 30 seconds and SHA-1. If the website view’s automatic codes already use a connection-local authenticator, Use the website’s authenticator selects the same one. Check code shows the current code, never the secret, until its time window ends, so you can compare it with your authenticator app.
• Vault credentials. Choose one of the vault entry’s authenticators. This is the same setting as General → Credential source → Vault authenticator for login challenges, so changing it here also turns off the website view’s automatic codes until you enable them again. If the entry has no authenticator, add its secret to the entry in Settings → Security → Database credential vault, then choose Reload authenticators. A connection-local authenticator is ignored while vault credentials are selected.

The section warns when the chosen authenticator is gone or has no secret; until you choose again, codes are typed manually.

The Synology access settings store only which authenticator to use, never its secret. The secret is never sent to DSM: only the generated code is, in the same sign-in request as the password and over the connection’s chosen transport.

A sign-in uses the authenticator like this:

1. The app signs in without a code first and generates one only after DSM answers Code required (403). When DSM accepts a trusted device, no code is needed.
2. If less than 3.5 seconds remain in the current time window, the app waits for the next window so the code can’t expire on the way.
3. The app doesn’t send an automatic code from a time window in which a code, typed or automatic, may already have signed in to the same NAS address and DSM account. Reconnecting or reopening the connection within that window waits for the next one, up to one period (30 seconds for DSM). The app keeps this only in memory, and never keeps the code.
4. The code is submitted once. If DSM accepts it, the session opens without a dialog.
5. Otherwise the Two-factor authentication dialog opens with its code field and a notice, and nothing more is tried automatically:
   • “DSM rejected the code generated from the saved authenticator. Check the authenticator secret and this computer’s clock, or enter a code.” DSM refused the generated code.
   • “The saved authenticator couldn’t produce a code. Enter the code from your authenticator app.” No code could be generated, for example because the vault is locked, the authenticator was removed, or a database export removed its secret.

Type a code from your authenticator app to continue, or choose Cancel sign-in. A rejected code usually means the saved secret isn’t the one enrolled for this DSM account, or this computer’s clock is wrong.

How this differs from the DSM website view’s Automatic 2FA. The website view’s automatic codes are a separate, off-by-default consent for one HTTPS origin: they need certificate verification and a reviewed DSM code challenge, and they enter a code on DSM’s own sign-in page. See two-factor and Secure SignIn steps. The NAS API authenticator needs no origin review because the code goes only into the API sign-in request, so it also works over an HTTP transport. With local credentials each view keeps its own authenticator choice, and choosing one never enables the other view. With vault credentials both views read the same vault authenticator, but the website view still needs its own origin consent. Signing in on one view doesn’t sign in the other.

Trust this device

In the code dialog of a saved connection, Trust this device for this NAS account asks DSM to remember this computer once the code is accepted. Later sign-ins from this computer then skip the code, including Connect after the session expires. It is off by default. Automatic vault-authenticator sign-ins show no dialog; to trust the device for those, turn on Trust this device after a successful two-factor sign-in in the connection’s Synology access settings. The dialog checkbox still changes it for a single sign-in. A notice confirms the result, or tells you that DSM didn’t issue a trusted device, in which case the next sign-in asks for a code again.

• Vault only. The connection’s credentials must be in the credential vault; for local credentials the option is shown disabled, including when a connection-local authenticator answers codes automatically. DSM’s device token is stored only in that vault entry, encrypted with the owning database. It never goes in the connection record, the page or error text, and it is never displayed.
• Not portable. Encrypted vault archives never include trusted devices, and importing an archive drops any it contains. Database exports refuse vault data.
• Bound to this computer’s name. DSM lists the device as SortOfRemoteNG · <computer name>, and the app sends the token only when that name matches this computer. The same database on another computer, or a renamed computer, asks for a code again and forgets the saved device. One device is kept per NAS address and account, so a database used on two computers makes each computer trust itself again in turn. This check prevents silent reuse of a copied database; it does not protect against someone who has the unlocked database.
• macOS. The app usually can’t read a Mac’s computer name, so every Mac is named SortOfRemoteNG · desktop and the name check can’t tell two Macs apart.
• No longer accepted. When DSM rejects the saved device, for example after it was removed in DSM, the app forgets it, shows “This NAS no longer accepts the saved trusted device”, and asks for a code. A vault authenticator is still tried at most once.
• Forget it. While connected, choose Forget this device in the trusted-device bar. On the sign-in screen, choose Forget trusted device. In the vault, open the entry’s Trusted NAS devices, choose Forget trusted device, then save. Forgetting only removes the app’s copy: to revoke the device on the NAS, sign in to DSM, open Personal › Security and remove it from the account’s trusted devices.

Manage files

• Browse with folder names, breadcrumbs, the parent-folder button, or an absolute NAS folder path. Lists use pages of up to 100 entries with name, size, type and modified-time sorting.
• Search within an open shared folder. Search results are paginated; clear the search field and choose Search to return to the folder list.
• Select individual entries or the current page. Create folders, rename one entry, or review a multi-selection before copying, moving or deleting it. Copy and move require an existing absolute destination inside a share.
• Upload opens the native local-file chooser. Download saves one selected file through the native Save dialog: choose a new filename, because existing local files are never overwritten, even if the operating-system dialog offers overwrite confirmation. Cancelling the dialog is not reported as a successful transfer. Existing destination files are not overwritten or silently skipped.

Copy, move, delete and search wait for the NAS task’s completion, not merely acceptance of the request. Known progress is shown; Cancel task requests cancellation without undoing changes already made. Inspect the NAS afterward. Failed cancellation remains visible and can be retried. No file operation is automatically retried.

Details & permissions displays the selected listing’s owner, group, size, timestamps, real path, POSIX mode and ACL mode where supplied. Missing metadata is unknown. ACL editing is not exposed. Share selected item reviews the selected path before creating a link, with an optional password of up to 16 characters and an optional expiry date. Sharing links lists up to 50 links per NAS page and supports explicit, individually confirmed revocation. Links are not automatically opened. Sharing passwords are transient, and revoking a link does not delete its file. These bounds follow the File Station API guide.

Delete recovery depends on the NAS shared-folder recycle-bin configuration and is not guaranteed. NAS shared folders are administered separately in Shares, with distinct create/delete and encrypted-share lock/unlock confirmations. Permissions, quotas, installed packages, licenses and DSM version can limit individual operations.

Changing or disconnecting the NAS invalidates open action reviews. Native operations are tied to both the viewer instance and the captured session, including after local file dialogs; stale callbacks cannot operate on a replacement NAS. Saved-session operations also check current access to the owning database. Locking, switching or closing that database revokes its session. A definitive expired DSM session requires signing in again; mutations are never automatically replayed. Closing the viewer clears pending login secrets and requests cleanup of owned tasks and sessions. Merely hiding a tab pauses administration polling without signing out or cancelling a running NAS task.

Administration and availability

Native Synology support requires a desktop build with the ops and platform capabilities (the full / full-dev profiles include them). Before credentials are resolved, the app also requires the running backend’s versioned syn_fs_transport_capabilities marker to confirm HTTP proxy and QuickConnect support. A missing or old marker requires restarting/updating the desktop app; reloading its web page or retrying a password cannot add native commands. Developers must rebuild and relaunch the desktop process.

The native explorer supports the app-wide direct route or configured HTTP(S) proxy, with the same route and private NAS cookie jar retained for the session. It does not consult environment proxy settings or silently bypass a failed proxy. Changing the app-wide proxy requires reconnecting. Per-connection proxy/VPN/tunnel chains and custom browser certificate exceptions remain unsupported and are refused visibly; HTTPS uses verified system TLS. Use the DSM website access mode when a browser-based sign-in is more appropriate. Its authentication remains separate from the API session, and neither passwords nor one-time codes are retried automatically. This is not a guarantee of compatibility with every DSM version or installed package.

Tables provide local search and 25-row display pages. System and connection logs additionally expose 100-entry NAS pages. Visible administration views refresh every 30 seconds, with overlapping refreshes suppressed and manual Refresh available. A — cell means DSM didn’t report that value; it is not zero. When a read fails for a reason other than access, Some data could not be refreshed lists each failed read with its API failure details and Copy diagnostics. Its values are cleared so stale data isn’t shown, and Refresh tries it again. An expired session, missing package, access restriction or incompatible response is never shown as successful empty data. The last checked time describes the most recent refresh attempt, not a health guarantee.

Actions are explicit forms, not arbitrary API execution. Row buttons prefill the target’s actual ID. Every write is reviewed with its target NAS and effect; acknowledgement means the NAS accepted the request, not that a reboot, package installation, backup or image download has finished. Inspect the refreshed status. File tasks separately poll their documented completion flag. Camera snapshots are bounded PNG/JPEG previews, not recording downloads. Container project start and stop accept the project’s name or its id.

Download-task deletion’s Move incomplete files to destination option is deliberately off by default. It controls Synology’s force_complete behavior; it does not validate or complete partial content. See the Download Station API guide.

Access checks and restricted data

The sidebar checks each section’s reads once per API session, with at most three checks in flight, and pauses while the session tab or app is hidden. Every read is checked on its own, so a section counts as available only when all of its reads are. A check sends the same request its table loads, asking for one row where the table pages. Once per sign-in it also asks DSM whether the account is an administrator; that answer only chooses the explanation and never hides data DSM allows. A section check takes at most 10 seconds and each read at most 3 seconds, plus up to 5 seconds for the administrator lookup. A read that doesn’t answer in time is Could not verify, not a denial.

In the sidebar, a fully readable section shows a check mark. Partial access keeps the section in the list: readable tables show their rows and the others show a notice. A section with nothing readable moves to one of two collapsed groups, Needs more access (n) or Not installed or not provided (n). Select a grouped section to open its explanation, which lists the refused reads and their DSM APIs and names the signed-in account. Could not verify sections stay in the list.

Most administration data is administrator-only in DSM: resource usage, storage, shared folders, network, users and groups, packages, services, security, UPS, power schedule and system logs. The Container Manager, Virtual Machine Manager, Hyper Backup and Active Backup for Business packages are administrator-only too. DSM 7.2 delegated administration can let another account view some of this data, which is why each read is checked instead of inferring access from the account’s role. For a standard or delegated account, the session panel notes that administrator-only data is hidden.

Restricted reads are not requested when a section opens, on Refresh or by the 30-second refresh; their tables show the notice instead. If DSM refuses a read (code 105) before the check has classified it, the table shows the notice rather than an error, and that section is rechecked once automatically. Recheck access on a notice rechecks its section, and Recheck section access under the sidebar rechecks every section. Data a recheck finds readable loads straight away. DSM may apply privilege or group changes only at the next sign-in, so if data stays restricted after you change DSM, reconnect.

Actions that need an administrator are disabled, with the tooltip Requires a DSM administrator account, only when every read in their section requires an administrator. With partial or delegated access they stay available, and DSM still checks each action when it runs.

DSM code 120 means DSM didn’t accept a request’s parameters. It is not a permission denial: the access check shows Could not verify, and a table load that gets 120 appears under Some data could not be refreshed without a restriction, so Refresh tries it again. The NAS may expect a different request on its DSM version; update the desktop app, and copy the diagnostics if it persists.

Firewall rules are read for each network adapter DSM lists, up to 32 adapters. SMART details for a disk are not requested while the Disks read needs more access. If DSM doesn’t recognize the SMART method (code 103), the app asks once more with DSM’s health-information method.

Command-to-interface coverage

This map describes the current native command surface, not universal DSM/package compatibility. All mounted commands carry the instance and session receipt. Commands grouped below share the visible tab or reviewed operation stated in the first column.

The legacy commands syn_connect, syn_disconnect, syn_is_connected, syn_check_session and syn_get_config are compatibility plumbing, not an alternate login path for saved sessions. Legacy syn_list_files, syn_list_file_shared_folders, syn_search_files, syn_upload_file, syn_download_file, syn_create_folder, syn_delete_files, syn_rename_file and syn_create_share_link are replaced in this interface by the receipt-bound File Station family. syn_get_camera_snapshot is replaced by the bounded typed snapshot command. Their presence does not authorize bypassing a saved session’s ownership, route or certificate checks.

This interface does not add unsupported ACL editing, VM restore, backup restore, remote mounts, archive extraction, arbitrary scripts or package upload. Browser-only DSM authentication must use the actual DSM origin in a normal browser; a localhost-proxied website may not support origin-bound security keys. Its cookies remain separate from this API login.