Office SDK
See the workflow
All storiesIntegration
IntegrationArchitecture4 min read

Document IDs, storage keys, and version IDs: what each should own

Separate business identity, stored objects, and editor sessions so renames, copies, and migrations remain predictable.

Office SDK EditorialOffice SDK Editorial
001
Document IDs, storage keys, and version IDs: what each should own: Business ID, Storage key, Version ID, Session ID.
Integration / Office SDK

Use a stable business document ID for links and permissions, a storage key for bytes, and a version ID for a particular saved state. An editor session needs a separate identity. This separation lets you rename, copy, restore, or relocate a file without accidentally changing who owns it or which content a link resolves to.

Four identities, four different responsibilities

The business document ID should identify the object that users discuss and permissions protect. A storage key identifies bytes at a location. A version ID identifies a particular state of those bytes. A session ID identifies one editing interaction. Record these relationships explicitly instead of deriving one value by removing a filename extension or concatenating a user name. A filename is useful display information, but it changes too easily to act as the foundation of authorization, links, or callback routing.

For creation, import, editing, export, and deletion, identify the component authorized to change the business record. An editor integration can request a save without owning the surrounding folder or retention policy. Conversely, your storage system may retain bytes while the business document is no longer visible. A small ownership table prevents these boundaries from becoming accidental. Include who generates each identifier, whether it is tenant scoped, whether clients can see it, and whether it survives a storage migration or a restore operation.

Four distinct identities connect access, saved state, stored bytes, and the editing session.
Figure 1. A storage relocation should change the object reference, not the business document ID.

A minimal mapping model

A minimal mapping can be expressed with three records. The business record contains tenant_id, document_id, and current_version_id. A version record contains its document relationship, storage object reference, and digest. An integration record maps that document to the external service's identifier within the correct tenant and provider scope. These are illustrative application fields, not a prescribed SDK schema.

ActionIdentity that staysIdentity that changes
RenameDocument and content versionDisplay name
CopyPossibly shared immutable bytesBusiness document and permissions
Restore contentBusiness documentCurrent version relationship
Relocate storageDocument and logical versionPhysical object reference

Enforce those relationships in storage constraints, not just application conventions. For example, a current version must belong to the same document and tenant as its parent record. During recovery, validate this relationship before making the document visible. A syntactically valid identifier pointing to another tenant's object is still an invalid mapping, even if a privileged storage account can read the bytes.

Copying Budget.xlsx creates a new business object

Suppose an employee duplicates a purchase template called Budget.xlsx into a project folder. The copy needs a new business document ID even when its initial bytes match the original exactly. Its first version may reference a deduplicated storage object, provided access and lifecycle rules support that choice. Sharing a storage object must not silently share collaborators, comments, editing sessions, or deletion behavior. A restore of the original document is different: it normally preserves business identity while selecting or creating a recoverable content version.

Rename, copy, and restore are compared by their effects on document identity.
Figure 2. Shared initial bytes do not make two copies the same business document.

Authorization and lifecycle checks

Hard to guess identifiers reduce accidental discovery, but do not establish access rights. Resolve the requested document inside the authenticated tenant and check the intended operation before creating an editor session or issuing a download link. Reject a callback whose external document identifier maps to another tenant, even if its syntax looks valid. Store integration mappings with a uniqueness constraint appropriate to the provider and tenant. Log mismatches using identifiers and operation names, without recording source bytes or reusable access tokens.

  • Rename a document and confirm that links and permissions still resolve to the same business record.
  • Copy it and verify that the new record has independent collaboration and lifecycle settings.
  • Restore an old version and document whether the action creates a new version or changes a version pointer.
  • Move storage objects without changing the public business identifier.
  • Attempt a cross tenant lookup and confirm that mapping resolution cannot bypass authorization.

Further reading

Back to all stories

Keep reading.

All stories