First steps

With the setup wizard done, these are the steps between an empty installation and a proven, restorable backup.

1. Create or select a tenant

A tenant is one customer or organization: it gets its own encryption key, and its data (sources, backups, users) is isolated from every other tenant by PostgreSQL Row Level Security. Community and Business editions manage exactly one tenant; Service Provider manages any number (see License and editions). Create the first one under Tenants → New tenant (a name and a slug used in exports and integrations, fixed once set), or switch into it with the tenant switcher in the top bar: most of the rest of Restow is scoped to whichever tenant is active there.

2. Connect Microsoft 365

Restow talks to Microsoft 365 exclusively through the Microsoft Graph API, never Exchange Web Services (EWS) or PowerShell remoting. Connecting a tenant has two parts: the backup app registration, done once per Restow installation (by you, the operator), and admin consent, done once per customer tenant.

Enter it under Settings, not only in .env

Once you have the client ID and a secret or certificate (steps below), enter them under Settings → Microsoft 365 in the web interface instead of editing .env by hand. That page repeats this permission list, links straight into the Entra admin center, and has Test connection to confirm the registration actually works before you rely on it. ENTRA_CLIENT_ID with ENTRA_CLIENT_SECRET/ENTRA_CLIENT_CERT_PATH in the server environment still works and takes precedence when set; Settings then shows the registration read-only (“from the server environment”).

2a. Register the backup app in Entra (once, as the operator)

In the Entra admin center (or the Azure portal), under Identity → Applications → App registrations → New registration:

1. Name: anything recognisable, e.g. Restow; customers see it on the consent screen.
2. Supported account types: choose the option that starts with “Accounts in any organizational directory” (the multitenant option). This is required so customer tenants outside your own can grant consent, not “This organizational directory only”.
3. Redirect URI: not needed for the client-credentials calls themselves, but required for the admin-consent return trip (step 2c). Type Web; the exact value comes from your RESTOW_PUBLIC_URL: <RESTOW_PUBLIC_URL>/api/v1/sources/m365/consent/callback.
4. Register, then note the Application (client) ID: this goes into ENTRA_CLIENT_ID.

Under API permissions → Add a permission → Microsoft Graph → Application permissions, add exactly these (all need admin consent):

Permission	Used for	Required
Mail.ReadWrite	Backing up and restoring mail. Read-only is not enough: restore writes.	Yes
MailboxSettings.Read	Time zone / regional settings.	Yes
Calendars.ReadWrite	Calendar backup and restore.	Yes
Contacts.ReadWrite	Contacts backup and restore.	Yes
Files.ReadWrite.All	OneDrive backup and restore (upload sessions).	Yes
User.Read.All	Directory sync, mailbox list, protection rules.	Yes
Group.Read.All	Resolving a group-based protection rule.	Yes
Directory.Read.All	Directory sync, deleted users, role checks.	Yes
Organization.Read.All	Tenant name and license info (display only).	Yes
Mail.Send	Only if notification mail uses the Microsoft Graph transport (setup wizard, or Settings).	Only if used

The classic mistake is granting Mail.Read instead of Mail.ReadWrite: backup runs fine, then every restore fails with a 403. Restow’s permission check (step 2d) catches and names this specifically.

Also add the delegated Microsoft Graph scopes openid and profile (under Delegated permissions). These give Restow no data access at all; they only let the admin’s confirming sign-in in step 2c complete without a second consent prompt.

Then, under Certificates & secrets, add credentials: a certificate (preferred; upload the public certificate, keep the private key off the repository, path in ENTRA_CLIENT_CERT_PATH) or a client secret:

1. Certificates & secrets → Client secrets → New client secret.
2. Choose an expiry: Microsoft caps this at 24 months.
3. Copy the Value immediately. Entra only shows it once; it is gone from the portal after you navigate away. Paste it into ENTRA_CLIENT_SECRET in .env (never into the repository, never into a log).

Fill exactly one of ENTRA_CLIENT_SECRET or ENTRA_CLIENT_CERT_PATH; if both are set, Restow uses the certificate.

2b. Add the Microsoft 365 source in Restow

Under Sources → Add source → Microsoft 365 tenant: give it a name, optionally a tenant ID or verified domain to send the admin straight to the right tenant, and a starting protection scope: all mailboxes and OneDrives or members of one group (a new source can’t start in “only selected objects” mode; switch to it afterward under Protected objects, see step 4, if that’s what you want). Restow creates the source in a “Not connected” state.

2c. Admin consent

Still on the source, Create consent link (valid for one hour). Open it yourself or send it to the customer’s Global Administrator. They sign in to their own tenant, review the requested application permissions, and consent for the whole organization. Then Microsoft returns them to Restow’s redirect URI, where they sign in a second time to confirm. That second sign-in is what lets Restow verify the tenant ID actually belongs to the admin who consented (rather than trusting an unsigned callback parameter), and that the account is a Global Administrator or Privileged Role Administrator: no lesser role can grant this consent. Restow records the confirmed admin’s account as “consent granted by”, and queues the tenant’s first directory sync immediately: mailboxes and OneDrives typically show up within moments, not after a six-hour wait.

A tenant can be connected to only one source in the whole installation; consenting again from an already-connected tenant is refused, without revealing which source it belongs to.

2d. Verify permissions

Once consent completes, Restow checks every permission automatically and shows a checklist (Verify permissions to re-run it). Each one is Granted, Read-only (the read/write mismatch above), or Missing. All required permissions must show granted before backups can run; re-run admin consent after fixing the app registration to update it.

3. Connect IMAP

Under Sources → Add source → IMAP mailbox: server host and port, connection security (TLS on 993, STARTTLS on 143, or unencrypted, development only, sends the password in clear text), username and password, and Test connection before saving to catch typos early. That one password applies to every mailbox you add under this source; OAuth2 sign-in for IMAP sources is in development.

IMAP sources have no Entra-style directory: add mailboxes as a manual list or import a CSV (login, name, email columns, in any order; comma, semicolon or tab all work).

In development

An IMAP source currently stores one password, shared by every account added under it. There is no per-mailbox IMAP credential yet. If your provider needs a distinct password per mailbox rather than a shared or admin credential, that is not supported in the current release.

4. Set protection rules

Under Protected objects → Sources and rules → Edit rules for a source: scope is everyone in the directory, members of one group (direct and nested members only), or only selected objects (nobody protected by default, only what you explicitly include), with an optional exclusion list (address, UPN or object ID, one per line; kept regardless of which scope is active) applied before the scope, and a toggle for whether shared/resource mailboxes are included (Microsoft Graph cannot tell a shared mailbox from a sign-in-blocked user apart, so this one setting covers both). Individual overrides (“always include” / “always exclude” on one object) beat the rule. Saving queues a directory sync that applies the change.

With “only selected objects”, include or exclude objects one at a time from the Protected objects page, or in bulk: check rows (or “select all N matching” the active filter, up to 1,000 objects at once) and apply Include, Exclude or “Follow the rules again”, each behind a confirmation naming the exact count. Every object gets its own audit entry; a large batch also gets one summary entry.

5. Run your first backup

You may find there’s nothing to trigger here: Restow queues a first backup automatically the moment an object becomes protected (an include, a directory sync finding it newly active, or an IMAP import), so a first run can already be queued or finished by the time you open this page. Back up now (per object) and Back up all are still there under Backup for running one again by hand. Watch progress live: items done/total, bytes, an ETA, and, for Microsoft 365, any throttling wait Microsoft imposes, shown in the job rather than hidden. A first backup of a large tenant can legitimately take days, not hours; this is Microsoft’s own rate limit, not a fault.

6. Confirm recovery readiness: don’t stop at “backup succeeded”

A backup Restow has not read back is not treated as trustworthy. Under Recovery readiness, either wait for the next scheduled check or Check now: Restow reads back a random sample of mails, files, calendar items and contacts from the latest backup through the restore path and compares their size and SHA-256 hash against the manifest. The result is Ready, Attention or Not restorable per object; an object with no verified restore counts as Not verified, not as quietly fine. There is no test restore into a live mailbox or OneDrive yet. See How Restow checks that a backup can be restored for exactly what this check does and does not check.

7. Run a first test restore yourself

Before relying on Restow in an emergency, restore something by hand: open Restore, browse a backup at a point in time, select an item or a folder, and restore it into the original location, into another account, or as a ZIP/EML download (see Backup and restore for exactly how targets and modes work). Confirm it landed where you expected and reads back correctly.

Once this is done, set up schedules so backups, verification and directory sync run on their own, and consider additional storage targets so a single storage failure can’t take every copy.