Biometric Passkey: Version policy
Introduction
This guide explains how Biometric Passkey versions are supported, which component combinations are supported together, and how to plan upgrades across the self-hosted backend and mobile SDKs. Use this page with the release notes for the version you are installing or upgrading to.
Components covered
Biometric Passkey has separately versioned release components. A production deployment normally includes one backend release set and one or more mobile applications that embed supported SDK versions.
| Component | How you consume it | Version selector |
|---|---|---|
| Backend | Versioned image archives for biometric-passkey-core, biometric-passkey-management, and biometric-passkey-migrate | Backend release tag and image archive version |
| Database schema | Applied by the biometric-passkey-migrate image that ships with each backend release | Backend release version |
| Android SDK | Maven Central package com.entrust.identity.biometricpasskey:android-sdk | Maven package version |
| iOS SDK | Public Swift package repository and hosted BiometricPasskeySDK XCFramework asset | Swift package semantic tag |
The backend images, migration image, and database schema are treated as one backend release set. Always run the migration image from the backend release you are deploying.
Version model
Backend and SDK releases use semantic version identifiers in the form X.Y.Z:
| Segment | Meaning |
|---|---|
X | Major version. May include breaking changes that require a planned migration. |
Y | Minor version. Adds supported functionality within the same major version. |
Z | Patch version. Contains fixes, security updates, or operational improvements within the same release line. |
A release line is the X.Y line of a component, such as 1.4.x. A specific release is a complete X.Y.Z version, such as 1.4.2.
Patch releases supersede earlier patches in the same release line. When more than one patch is available for a supported release line, use the latest patch unless your Entrust contact gives you a deployment-specific instruction.
Do not use floating version selectors in production. Pin backend images, Android dependencies, and iOS package versions to explicit release versions.
Supported versions
Biometric Passkey supports the current production release line (N) and the immediately previous production release line (N-1) for each component. For this policy, N means the latest generally available X.Y release line for that component, not the latest patch or the latest major version.
When Entrust releases a new major version, the final release line of the previous major version remains supported for the announced major-version transition window. This transition support is limited to the final previous-major release line unless your agreement with Entrust explicitly states otherwise. It does not automatically extend support to every earlier minor release line in the previous major version.
Older release lines are out of the standard support window unless your agreement with Entrust explicitly states otherwise. Within a supported release line, upgrade to the latest patch release before opening support cases for issues already fixed in a later patch. Security advisories can require a faster patch upgrade path than the standard support window.
Support for a release line means Entrust can provide troubleshooting guidance and fixes according to the applicable support terms. It does not mean every backend, database schema, Android SDK, and iOS SDK version can be combined arbitrarily. Use the compatibility matrix to choose supported combinations.
Compatibility matrix
Use this matrix before installing or upgrading backend, SDK, or database schema versions. The matrix is the source of truth for which backend release lines, database schema versions, Android SDK versions, and iOS SDK versions are supported together.
| Release set | Backend server | Database schema | Android SDK | iOS SDK | Status |
|---|---|---|---|---|---|
| GA 1.0 | 1.0.x | Schema shipped with backend 1.0.x migration image | 1.0.x | 1.0.x | Supported GA line |
For the initial GA release, use backend 1.0.0, the database schema applied by the backend 1.0.0 biometric-passkey-migrate image, Android SDK 1.0.0, and iOS SDK 1.0.0 together.
The database schema is not independently versioned. It is part of the backend
release set and is selected by the backend version you deploy. Always apply
migrations with the biometric-passkey-migrate image from the same backend
release as the Core API and Management API images.
Follow these compatibility rules unless the matrix for your target release explicitly states otherwise:
- Deploy backend images and database migrations from the same backend release.
- Do not run an older backend against a schema migrated by a newer backend release.
- Do not combine components from different major release lines.
- Use SDK release lines listed as compatible with the deployed backend release line.
- Treat patch versions within the same supported release line as compatible, but still review release notes for required configuration changes, database migration notes, and mobile SDK integration changes before upgrading.
Upgrade policy
Plan upgrades from the release notes and compatibility matrix for the target version. A safe upgrade plan identifies the exact backend image versions, migration image version, Android SDK version, iOS SDK version, validation environment, and rollback approach before production deployment.
- Review the release notes for breaking changes, deprecations, security fixes, database migration notes, SDK requirements, and compatibility updates.
- Confirm the target backend, database schema, Android SDK, and iOS SDK combination is supported by the compatibility matrix.
- Verify release artifacts before deployment. For backend releases, verify archive checksums before loading images into your registry.
- Back up the database according to your operational process before applying backend migrations.
- Upgrade backend releases with the matching
biometric-passkey-migrateimage before rolling the Core API and Management API images. - Deploy Core API and Management API images from the same backend release after the migration completes successfully.
- Validate enrollment, step-up, cross-platform step-up, recovery, management access, and monitoring in a non-production environment before production rollout.
- Roll SDK upgrades through your normal mobile release process and verify they remain compatible with the deployed backend release line.
If a backend upgrade includes database migrations, test the full upgrade path in a non-production environment using production-like data volume and operational settings. Do not assume database migrations can be rolled back unless the release notes explicitly describe a supported rollback procedure.
Deprecation policy
Breaking API changes use a new versioned path prefix, such as moving from /api/internal/v1 to a later major prefix, or are otherwise called out in release notes as breaking integration changes. The previous supported prefix remains available during the announced deprecation window.
Deprecation windows, migration targets, and removal dates are communicated through release notes and your Entrust contact. Treat deprecation notices as upgrade requirements and plan validation before the removal date.
