Backup destinations

A backup destination is a reusable storage target — an S3-compatible bucket, an SFTP server, a local filesystem path, or another Synq server — that backup policies write their archives to. FTP/FTPS servers, Dropbox and Google Drive are destinations too; the last two connect through OAuth with your own app (see Connect Dropbox or Google Drive). This API creates and manages those targets and runs a preflight that proves a destination is actually reachable (it writes, reads back, and deletes a probe object). Credentials are encrypted at rest; serialized destinations never return secret values, only hasX flags showing which are configured.

This module is available on both self-hosted and cloud instances. The local destination kind is self-hosted only — it is rejected in cloud mode and, on self-hosted, must be explicitly enabled (see below).

Create a destination

const result = await ship.backupDestinations.create({
  name: "prod-s3",
  kind: "s3_compatible",
  bucket: "my-backups",
  region: "us-east-1",
  accessKeyId: "AKIA...",
  secretAccessKey: "...",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/backup-destinations" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-s3","kind":"s3_compatible","bucket":"my-backups","region":"us-east-1","accessKeyId":"AKIA...","secretAccessKey":"..."}'

Required fields depend on kind:

• s3_compatible — bucket, accessKeyId, and secretAccessKey.
• sftp — sshHost, sshUser, and one of sftpPassword / sftpPrivateKey.
• synq_server — serverId (a server in your org).
• local — endpoint (an absolute path inside BACKUP_LOCAL_ROOT).
• ftp: ftpHost, ftpUser and ftpPassword. pathPrefix is the folder (absolute, or relative to the login folder).
• dropbox / google_drive: oauthClientId and oauthClientSecret. pathPrefix is the Dropbox folder (for example /Synq Backups) or the Google Drive folder name (default Synq Backups). The destination can't store backups until it is connected.

Update a destination

Send only the fields you want to change. For credentials, undefined (omitted) leaves the stored value unchanged, null clears it, and a string replaces it. The kind cannot be changed after creation.

const result = await ship.backupDestinations.update("bkd_123", {
  pathPrefix: "nightly/",
  isDefault: true,
});
console.log(result);

curl -X PATCH "$SYNQ_URL/api/backup-destinations/bkd_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pathPrefix":"nightly/","isDefault":true}'

Connect Dropbox or Google Drive

Dropbox and Google Drive destinations use an OAuth app you own: a Dropbox app (scoped access, with files.metadata.read, files.content.read and files.content.write) or a Google Cloud OAuth client of type Web application with the https://www.googleapis.com/auth/drive.file scope. After creating the destination with the app's credentials, connect it in two calls:

1. Start: send the redirect URI, which is the panel's own callback page (<panel origin>/backups/oauth/callback, HTTPS or localhost, registered in the app). The response has the provider URL to open in a browser.
2. Complete: the provider sends the browser back to that page with code and state. Post both. Synq exchanges the code for a refresh token (stored encrypted), records the approving account, creates or reuses the Google Drive folder, runs a preflight, and returns the destination.

const { authorizeUrl } = await ship.backupDestinations.oauthStart("bkd_123", {
  redirectUri: "https://panel.example.com/backups/oauth/callback",
});
console.log(authorizeUrl); // open it, approve access

// Later, with the query parameters the callback page received:
const destination = await ship.backupDestinations.oauthComplete({ code: "...", state: "..." });
console.log(destination.oauthConnected, destination.oauthAccount);

curl -X POST "$SYNQ_URL/api/backup-destinations/bkd_123/oauth/start" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"redirectUri":"https://panel.example.com/backups/oauth/callback"}'

curl -X POST "$SYNQ_URL/api/backup-destinations/oauth/complete" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"...","state":"..."}'

The state is sealed (encrypted and authenticated) by Synq and expires after 15 minutes. It only completes for the user and workspace that started the connection. The destination's read model shows the connection as oauthConnected, oauthAccount and oauthConnectedAt, and for Google Drive the folder as remoteFolderId; the refresh token and the app secret are never returned. When the provider stops honoring the refresh token (access removed, or a Google app left in Testing for 7 days), runs and preflights fail with a message that the access "was revoked or has expired"; start and complete the connection again to fix it.

Preflight (verify connectivity)

Proves the destination works by writing, reading back, and deleting a small probe object. On success it stamps lastVerifiedAt; on failure it records the error in lastVerifyError.

const result = await ship.backupDestinations.preflight("bkd_123");
console.log(result);

curl -X POST "$SYNQ_URL/api/backup-destinations/bkd_123/preflight" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

Errors

Operations