Upcoming Update to the ID Format of Spaces and Entities

Starting June 16, 2025, for US-based spaces, and June 23, 2025, for spaces in the EU, Canada, Australia, and China, performance and scalability will be increased by changing how IDs for newly created spaces, entities (e.g., stories, components, etc.), and partner and organization accounts are created. The current format will be replaced with a 53-bit number, offering significant improvements regarding security, speed of content deployment, backups, and more.

Overview of changes

The new ID format is based on the Snowflake ID format, encoding metadata into a 53-bit integer.

The following changes will take effect on June 16, 2025, for spaces located in the US and on June 23, 2025, for spaces located in the EU, Canada, Australia, or China.

Space IDs

The space ID is generated by encoding the region, the timestamp, and the sequence:

• 5 bits for region (up to 32 regions)
• 40 bits for timestamp (up to ~34 years after 2025)
• 8 bits for sequence (up to 256 sequences per timestamp)

As the first 5 bits of the ID are reserved for the region, the server location is discernible from the space ID as follows:

• 00001: EU
• 00010: US
• 00011: Canada
• 00100: Australia
• 00110: China

Entity IDs

The IDs used for stories, components, folders, workflow stages, users, etc., are based on the timestamp and sequence:

• 40 bits for timestamp (up to ~34 years after 2025)
• 13 bits for sequence (up to 8,192 sequences per timestamp)

GraphQL API

In GraphQL API version 1, the current integer bit size limitation will be lifted to maintain backward compatibility. Both the existing and new ID formats will continue to be returned as integers.

The introduction of the new ID format will coincide with the release of GraphQL API version 2, which will no longer return IDs as integers. Instead, IDs will be returned using the GraphQL ID scalar type. Migrating to version 2 is strongly recommended to ensure a standardized GraphQL experience. Additional details will be provided in the API documentation upon release.

Advantages

Enhanced security

By introducing non-sequential, 53-bit globally unique IDs, Storyblok enhances platform security. The new IDs prevent attackers or competitors from inferring internal data patterns, such as user identifiers or regional usage, and make unauthorized ID enumeration impractical.

Accelerated content deployment

By moving to globally unique, locally generated 53-bit IDs, Storyblok can accelerate content deployment by eliminating the need for centralized ID coordination. This allows for faster, conflict-free publishing, especially in multi-region and high-throughput scenarios.

More efficient backup recovery

With globally unique IDs, we can simplify and speed up backup recovery and space overwrites by removing the need for remapping or conflict checks. This enables faster rollbacks, environment cloning, and disaster recovery processes.

Frequently asked questions

Are my existing spaces affected?

Old records will not be affected. The changes enter into effect on June 16, 2025, and June 23, 2025, respectively, and affect spaces and entities created afterward.

Importantly, note that new stories and other entities (such as data sources, components, users, etc.) created in existing spaces (i.e., created before June 16 or June 23, respectively) are also subject to the new format.

Let's consider a few practical examples.

1. You create a space before June 16/June 23. It will have an ID in the current format, e.g. 345123. A story created in that space before June 16/June 23 will have an ID in the current format, e.g. 671471598. These IDs will not change after June 16/June 23.
2. However, a story created after June 16/June 23 will have an ID in the new format, e.g. 6221938447591433. Both stories, with different ID formats, will coexist in the same space.

In short, any new entity record created after June 16/June 23 will use the new ID format.

Are there going to be updates to tooling and SDKs?

Yes. While the updated ID format does not break any existing functionality provided by Storyblok’s open-source packages, the region identifier included in the new space ID format presents the opportunity to omit the region parameter when using the Management API with the JS or PHP client, or the CLI, further improving the DX. Stay tuned for future releases.

Are there any breaking changes? Are my serverless functions, external databases, or custom integrations impacted?

No. However, you may need to update your custom implementation. For example, if your external database is currently not configured to handle 53-bit-sized IDs in the column(s) utilized for space or entity IDs, it needs to be updated. Similarly, if you utilize strict type checking, for example, in your serverless functions, the code has to be updated to process the new format.

Are plugins affected?

Any plugins using the OAuth 2.0 Authorization Flow in conjunction with newly created spaces subject to the new ID format need to be updated.

Why 53 bits in particular?

This choice was made with JavaScript compatibility in mind. JavaScript’s Number type is a 64-bit floating-point number, which only safely supports 53 bits. Beyond that, numbers can lose precision, causing issues such as duplicate IDs or incorrect sorting.

Let us know if you have any questions about this upcoming change. We’re happy to talk to you on Discord or via our Help Center.