Skip to content

Concepts ​

This page explains the ideas behind Atlas and the terms you will meet in CLI output, error messages, and the rest of the documentation.

Packages: CLI and SDK ​

Atlas ships as two npm packages built on the same engine:

@wisecom/atlas-cli@wisecom/atlas-sdk
Installnpm install -g @wisecom/atlas-clinpm add @wisecom/atlas-sdk
InterfaceShell commands such as atlas outlook backupTyped methods such as atlas.outlook.backup()
Config.env file, environment variables, or atlas configObject passed to createAtlasInstance()
Best forCron jobs, systemd timers, operator workflowsCustom applications, multi-tenant services, portals

Both cover every workload. The CLI suits scheduled jobs and operators. The SDK suits applications that call Atlas from code.

Workloads ​

Atlas backs up six Microsoft 365 workloads. Each has its own CLI namespace and its own area in the tenant's bucket:

WorkloadCLI namespaceWhat you back upWhere it is stored in the bucket
Outlookatlas outlookA mailbox (email address or Entra object ID)Bucket root: data/, attachments/, manifests/
Contactsatlas contactsA mailbox's personal contactscontacts/
Calendaratlas calendarA mailbox's calendarscalendar/
OneDriveatlas onedriveA user's drive (email, UPN, or Entra object ID)onedrive/
SharePointatlas sharepointA site (URL or Microsoft Graph site ID)sharepoint/
Teamsatlas teamsA team (Microsoft Graph team ID)teams/

All workloads in a tenant share one bucket and one data key. Commands that work across workloads, such as atlas stats and atlas delete --purge, act on the whole tenant. Storage layout shows every path.

Snapshots ​

A snapshot is a point-in-time record of what Atlas backed up. It is not a full copy of the data. Each snapshot is a manifest, a JSON file in the bucket that lists items with their metadata: IDs, paths or folder names, SHA-256 checksums, and the object paths that hold the encrypted content.

The content itself is stored separately and shared between snapshots. A message that is still in the mailbox next week points to the same stored object as today's snapshot, so it is stored once.

  • Snapshots are written once and never modified.
  • Outlook, OneDrive, and SharePoint snapshots record only the changes of their own run and build on the snapshots before them. Only the newest snapshot can be deleted on its own; deleting an older one is refused with ATLAS_SNAPSHOT_NOT_NEWEST (exit 11). Contacts and Calendar snapshots are complete on their own.
  • With Object Lock enabled on the bucket, retention protects manifests from deletion for the configured period. See Immutability.
  • A run that finds no changes writes no new snapshot, so the latest snapshot stays current.
  • An Outlook snapshot also records the messages its run saw deleted, so a restore from it does not bring them back. A run that skipped a folder mail could have moved into, such as Junk Email with --exclude-junk, records none.

backup prints the ID of each snapshot it creates, and list or list-snapshots shows earlier ones. Commands that read a snapshot, such as atlas outlook list -s <snapshot-id>, atlas outlook restore -s <snapshot-id>, and the other workloads' restore, save, and verify commands, use its manifest to find and decrypt the objects they need.

Snapshot IDs ​

WorkloadFormatExample
OutlookA UUID3f2b8c1e-7a4d-4e9b-9c2a-5d6e7f8a9b0c
Contactsct-snap-<milliseconds>-<6-hex>ct-snap-1735689600000-a1b2c3
Calendarcal-snap-<milliseconds>-<6-hex>cal-snap-1735689600000-a1b2c3
OneDriveod-snap-<milliseconds>-<6-hex>od-snap-1735689600000-a1b2c3
SharePointsp-snap-<milliseconds>-<6-hex>sp-snap-1735689600000-a1b2c3
Teamsteams-snap-<milliseconds>-<6-hex>teams-snap-1735689600000-a1b2c3

<milliseconds> is the snapshot's creation time as Unix epoch milliseconds.

Each item is stored once ​

Atlas names every stored message, attachment, and file after its content, so identical content is written only once.

  • Same message in several snapshots of one mailbox: an unchanged item adds a manifest entry, not a second copy.
  • Same file across OneDrive versions: uploading identical content again writes no new object.
  • Same content in two mailboxes, drives, sites, or teams: stored once per owner. Deduplication never crosses owners, and tenants never share objects.

The name is an HMAC-SHA256 of the plaintext, keyed with a naming key derived from the tenant's data key and prefixed by the owner's ID, for example data/<owner-id>/<content-name> for Outlook messages and attachments/<owner-id>/<content-name> for their attachments. Because the name depends on your key, someone with access to the bucket cannot test whether a known file is stored there.

Deleting a snapshot removes only its manifest, because other snapshots may still reference the same objects. Deleting a whole mailbox, drive owner, site, or team removes its content objects as well. See the workload guides and the CLI reference for the delete commands.

Encryption keys ​

Atlas uses two keys, where one locks the other. Security describes the full model.

KeyTechnical nameWhat it is
Data keyDEK (data encryption key)A 256-bit AES key generated once per tenant. It encrypts all content in the bucket. It is stored only in wrapped (encrypted) form at _meta/dek.enc, a self-describing blob whose header records the key derivation parameters.
Passphrase keyKEK (key encryption key)Derived from your passphrase with scrypt (N=65536, r=8, p=1), a random salt for each wrap, and the tenant ID as a domain separator. It wraps the data key with AES-256-GCM. It is never stored: Atlas derives it again from the passphrase whenever it needs it.

A copy of the bucket therefore holds ciphertext and key derivation parameters, but no usable key. The passphrase is the only way back in.

Passphrase loss means data loss

Without the passphrase, the data key cannot be unwrapped and the backups cannot be read. Atlas has no recovery key.

Incremental backups ​

After the first full backup, Atlas asks Microsoft 365 only for what changed since the previous run. It keeps a sync checkpoint (a Microsoft Graph delta link) that marks where the last run stopped in the change history:

WorkloadOne checkpoint per
OutlookMail folder
ContactsContact folder
CalendarCalendar
OneDriveDrive
SharePointDocument library
TeamsChannel

When a checkpoint cannot be used, Atlas reads that folder, drive, or channel in full. --full forces a full backup. See Delta sync for when this happens.

Glossary ​

Each plain term used in these docs, and the technical term you will see in output, flags, and error messages.

Term in these docsYou will also seeMeaning
Tenanttenant IDA Microsoft 365 organization, identified by its Microsoft Entra tenant ID (a GUID). Each tenant has its own bucket, its own data key, and its own backups across all workloads.
Tenant profile--profile, atlas tenantsOne stored app registration for a tenant. See Configuration.
Ownerowner ID, -o, -mThe mailbox, OneDrive user, site, or team a backup belongs to. Users and mailboxes are stored under their Entra object ID. The CLI accepts an email address or UPN and looks up the object ID.
Sitesite ID, --siteA SharePoint site, identified by URL or Microsoft Graph site ID. Storage uses the site and web GUIDs without the hostname, so renaming the SharePoint domain does not start a new history.
Snapshotmanifest, -s <snapshot-id>A point-in-time backup record: a manifest plus the objects it references.
Full backupfull sync, full crawl, --fullA run that reads everything, ignoring the saved sync checkpoint.
Incremental backupdelta sync, delta queryA run that reads only changes since the last sync checkpoint.
Sync checkpointdelta link, delta cursor, delta stateThe saved position in Microsoft 365's change history that the next incremental backup starts from.
Data keyDEK, dek.encThe per-tenant key that encrypts content.
Passphrase keyKEKThe key derived from your passphrase that wraps the data key.
Object pathstorage key, --keyThe path of one object in the bucket. See Storage layout.
List of failed filesfailed-item ledger, failed itemsFiles that could not be backed up, retried on later runs and reported until they succeed or are permanently skipped.
One operation at a timelease, ATLAS_OWNER_BUSY, lease_expires_atAtlas runs one operation at a time per mailbox, drive owner, site, or team. A second one is refused and writes nothing.
Replicareplica endpointA second copy of the tenant bucket, kept by the storage provider or a copy tool in another location. Atlas restores from and verifies it when pointed at its endpoint. See Replicas.

See also ​