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 one tenant (managing several tenants is part of Service Provider); Service Provider manages any number, for your own customers (see License and editions). Create the first one under Tenants → Manage tenants → New tenant (a name and a slug used in exports and integrations, fixed once set; in a fresh installation, Overview links there with Go to tenants), 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. The pages that set up the tenant (Protection, Sources, Schedules, Retention, Imports) are tabs of one setup area: Tenant settings in Community and Business; a service provider opens it for a tenant with Open tenant page in the tenant switcher or in the row menu of All tenants.

2. Connect Microsoft 365

Restow talks to Microsoft 365 exclusively through the Microsoft Graph API. It never used Exchange Web Services (EWS), which Microsoft began switching off for Exchange Online in stages on 1 October 2026 (permanent retirement on 1 April 2027), and it does not use 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 Installation → Microsoft multi-tenant app 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, also of Microsoft 365 group calendars (since 0.4.5).	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; since 0.4.5 also finding Microsoft 365 groups and backing up their conversations (no new permission).	Yes
Directory.Read.All	Directory sync, deleted users, role checks.	Yes
Organization.Read.All	Tenant name and license info (display only).	Yes
Sites.ReadWrite.All	SharePoint Online (since 0.4.0): finding, backing up and restoring sites. Sites.Read.All is enough to back up, not to restore.	Only for SharePoint
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.

SharePoint is optional. Without Sites.ReadWrite.All Restow backs up mail and OneDrive as before, but finds and backs up no SharePoint sites; the directory sync warns about it (sites_unavailable) and the permission checklist shows a notice. With only Sites.Read.All, sites are backed up but a restore into a site fails (a download as ZIP still works). Add the permission before the customer consents, so that one consent covers everything. For how SharePoint is backed up and restored, see SharePoint Online; the product repository has a longer setup guide, ENTRA-SETUP.md (written in German).

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. Note the date: Restow reminds you before it runs out, see Expiry of the secret or certificate.
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 Tenant settings → Connections → 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 on the Protection tab, see step 4, if that’s what you want). SharePoint sites follow their own switch, on by default, see step 4. 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, OneDrives and, if the app registration has the SharePoint permission, SharePoint sites 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. The SharePoint permission is marked Optional: while it is Missing, the checklist shows the notice SharePoint sites are not backed up (or, with only Sites.Read.All, SharePoint sites can be backed up, not restored into), and nothing else is held back.

Expiry of the secret or certificate (since 0.4.7)

A client secret lives at most 24 months, and when it runs out every Microsoft 365 backup that uses the app fails. Since 0.4.7 Restow reminds you 30 days before, again 7 days before and once it has expired (the bell, and the mails and webhooks of every rule that lists the event), each stage once per expiry date. It needs the date, because it does not read it from Microsoft Graph:

• Entered under Installation → Microsoft multi-tenant app: give the secret’s expiry date in the field Expires on, as Entra shows it under Certificates & secrets. The page shows Expires with a badge that turns amber 30 days before the end and red from 7 days.
• Secret in .env: set ENTRA_CLIENT_SECRET_EXPIRES_AT (YYYY-MM-DD, for example 2027-03-01) next to ENTRA_CLIENT_SECRET and recreate the api; the page says so while the date is missing. Without a date there is no reminder, and the page shows the expiry as not recorded.
• Certificate: nothing to enter, Restow reads the certificate’s own end.
• Renewing without a gap: create the new secret in Entra, enter it with its new date, and only then delete the old one. A new date starts the reminders over.

A source that is connected through an app of its own has its own date and its own reminders, see Reminders before an app credential expires.

Adding a permission later (re-consent)

A permission that you add to the app registration after a customer consented does not apply in that customer’s tenant until their admin consents again. This is what happens for SharePoint on an installation that was connected before 0.4.0, and it holds for every permission you add later. First add the permission to the app registration, then on each Microsoft 365 source choose Create new consent link (valid for one hour) and send it to a Global Administrator or Privileged Role Administrator of that tenant. They consent and sign in a second time as before; the link only works in the tenant that is already connected. Then run Verify permissions. Until the new consent is given, everything that worked keeps working; only what needs the new permission stays off. Once the consent is given, the permission applies without a new client secret (since 0.4.7): a token carries the permissions the app had when Microsoft issued it, and Restow used to keep it for up to about an hour, so a permission granted in between was refused until then. Now, when Microsoft Graph answers 401 or 403, Restow fetches a new token once and sends the request again (at most once a minute per tenant or source), so a permission you granted works within about a minute. This holds for backups, restores, the directory sync, the archive capture, the group search, the connection test and the permission check. The one exception is notification mail through a Microsoft 365 app registration: a Mail.Send permission granted later takes effect once the cached token expires. A source that is connected through its own app has no consent link: add the permission to that app registration in the customer’s Entra admin center and grant admin consent there.

3. Connect IMAP

Under Tenant settings → Connections → 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), and how the source signs in. Each source uses one of three modes, so pick the one your provider supports:

• Shared login (the default): one login and password on the source, used for every mailbox under it. Use Test connection before saving to catch typos early.
• Own password per mailbox: for providers where every mailbox has its own password. The source itself has no login to test; add the mailboxes, then use Set password and Test sign-in on each mailbox in the Directory tab.
• Master user: one master account signs in as each mailbox (the master*mailbox form that Dovecot uses, or SASL PLAIN with an authorization ID).

OAuth2 for IMAP sources is not implemented yet; planned. See Connecting sources for the three modes.

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; an optional password column sets the mailbox password when the source uses a password per mailbox).

4. Set protection rules

On the Protection tab (Tenant settings → Protection), under 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). SharePoint sites (since 0.4.0) have a switch of their own, Protect all SharePoint sites: on by default, so every site of the tenant is backed up; switch it off to back up only the sites you include one by one. The scope, the exclusion list and the shared-mailbox toggle do not apply to sites. 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 on the Protection tab, 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. To run one again by hand, use Back up now on the Protection tab (all protected objects) or the link Back up per object next to it, which opens the page with Back up now for a single object. Watch progress live under Daily → History: items done/total, bytes, an ETA, and, for Microsoft 365, any throttling wait Microsoft imposes, shown in the run rather than hidden. The first backup of a large mailbox shows First backup: X of Y items with an estimated time left; a OneDrive shows X items so far until it is fully listed. The sidebar shows a spinner with the number of running backups, and a click opens the run’s live view (see Backup jobs). 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 Daily → Recovery readiness, either wait for the next scheduled check or Check now: Restow reads back a random sample of mails, files (also those of SharePoint sites), 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. It does not restore into a Microsoft 365 mailbox, OneDrive or IMAP account: the optional test restore into a target is not wired up in 0.4.7. 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 Mail & SaaS → Restore explorer, 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. If you back up SharePoint sites, try one file and one list item of a site as well (see SharePoint Online): SharePoint backup has not yet been run against a real tenant.

Once this is done, set up schedules so backups, verification and directory sync run on their own, and consider additional repositories (Tenant settings → Repositories) so a single storage failure can’t take every copy.