The road to Passbolt version 5 - Getting started with the new resource types

Passbolt v5 introduces a full redesign together with major changes to the security model. At the heart of these changes is encrypted metadata, the foundation on which the new resource types and capabilities (such as multiple urls, icons, custom fields, secure notes, etc.) are built. 

With the release of v5.5.0, encrypted metadata is now stable and enabled for all users. It is no longer experimental and is supported across both self-hosted and Cloud instances.

If you are running a self-hosted instance installed after v5.4 (August 12th) or a Cloud instance created after v5.5 (September 18th), encrypted metadata is already enabled and you can ignore this guide; otherwise, it is for you.

Requirements:

• Passbolt >= v5.5.0
• Passbolt self hosted or Cloud

Any considerations prior to enabling the feature?

While this new architecture has passed a full Cure53 security audit (see report) and has been battle-tested over the past months, it remains a major upgrade. As with any significant change, we recommend understanding the risks and limitations before enabling it.

To help you decide whether the feature set is ready for your environment, here are the current limitations as of v5.5:

• Performance impact. This capability introduces an additional cryptographic layer, which increases payload size and processing time. Depending on how you use Passbolt, this may have an impact on both infrastructure and user experience. If you manage several thousand resources, we recommend testing the feature in a staging environment first to evaluate its impact on your setup.
• Metadata key rotation. At this stage, it is not yet possible to rotate the metadata key. This feature will be introduced with v5.6. Until then, if a breach were to occur, you would not be able to rotate the key and re-encrypt the metadata, which is an important limitation to be aware of.
• Passbolt  CLI compatibility. The command‑line utility is still being updated for the new resource types. If you have automations that depend on it, consider waiting.

Even after these items shipped, some gaps will remain that you may want to evaluate before enabling the feature:

• Cryptographic verification of metadata origin. A signature mechanism is planned to confirm who encrypted each piece of metadata. Cure53 flagged this as an outstanding risk. A mitigation is in the work, see the proposal for details.
• Limited auditability. Organisations that rely on syslog or custom SIEM integrations will lose visibility into operations on v5 content because metadata remains encrypted.
• Custom integrations. Any bespoke integrations that call the API will need to handle the additional encryption layer and therefore will break if not adapted prior to the migration of the existing content. Updated SDKs are planned but not yet scheduled for release.

Enable the new resource types

If you haven’t yet configured your organization’s metadata encryption preference, you can enable it quickly using the simplified getting started wizard with just one click. If your setup is already configured, no problem, we’ll guide you through the process step by step.

One-click getting started

If you haven’t yet configured your organization’s metadata encryption preference, you will find a Getting started option under the Resource types menu in your organization settings. 

To enable the capability you can:

1. Navigate to Administration > Resource types > Getting started.
2. Check the Enable encrypted metadata and new resource types toggle.
3. Save the settings.

That’s it, encrypted metadata is now enabled for your instance. Keep in mind that existing content is not automatically migrated, only new content will use this capability. When you’re ready to migrate your existing content, refer to the Migrate existing content section

Step by step getting started

If your organization’s metadata settings were previously configured, you will have access to more fine-grained options and can enable the feature from there. This section walks you through the process. For a detailed explanation of each option, please refer to the administrator documentation.

Create a metadata key

Encrypted metadata requires an organization-wide shared metadata key, and this key must be created manually by an administrator.

1. Navigate to Administration > Resource types > Metadata key.
2. In the Shared metadata keys section, click on Generate key.
3. Save the settings.

Enable encrypted metadata

Encrypted metadata is one of the key structural changes in v5 resource types. It must be enabled and set as the default format to take full advantage of the new capabilities.

Navigate to  Administration > Resource types > Encrypted metadata.

1. In the Support metadata section, toggle on the “Enable encrypted metadata” setting to make v5 resource types available to all users.
2. In the Default metadata type section, enable the “Encrypted metadata” setting. This ensures that client applications (web and mobile) will create resources using the v5 format by default.
3. In the Self served migration section, enable the “Allow users to upgrade their content” if you want all the users to be able to update their existing content manually to the new resource types and benefit from the new capabilities.
4. Save the settings.

That’s it, encrypted metadata is now enabled for your instance. Keep in mind that existing content is not automatically migrated, only new content will use this capability. When you’re ready to migrate your existing content, refer to the Migrate existing content section

Migrate existing content

Encrypted metadata is now active, so every new item already benefits from icons, multiple URIs, and custom fields. The next step is to bring the same capabilities to the existing resources you created before the switch. This is the most delicate phase of the rollout. Make a verified backup of your instance before you begin; if anything goes wrong, a backup is your only safety net. 

Once your integrations are migrated and you are ready, here the final migration procedure follows.

1. Navigate to Administration > Migrate metadata.
2. In Items to migrate, switch on Resource to include every resource.
3. In Migration scope, switch on All content so resources from all users are covered.
4. Click Migrate and wait for the process to finish. How long it takes depends on the size of your workspace.

Conclusion

Thank you for taking the time to try these new features. They have been a long-running effort, and your experience matters to us. If you encounter any issues or have suggestions, please post on the community forum, the team is eager to hear your feedback.

Last update: September 18, 2025