Digital credential migration: platform cutover and verification continuity
Moving digital credentials from one platform to another is not a file-copying exercise. The issuer has to preserve the meaning of each claim, map the source records into the target model, prevent duplicate active credentials and keep a clear verification route for recipients and verifiers.
This guide covers vendor-to-vendor migration for an existing credential program. It does not own paper-certificate digitization, an Open Badges 2.0 to 3.0 format upgrade or holder-wallet portability. Those are separate decisions with different sources of truth and acceptance tests.
Short answer: Treat platform migration as a governed record cutover, not a file copy. Preserve the approved claim and issuer identity, assign every source record a target disposition, test recipients and verifiers, and keep a cohort-level rollback point.
Short answer
A safe digital credential migration starts with an inventory and a field mapping, then moves a small representative cohort through import, issuance, delivery and verification. Keep the old system available until each migrated record has a documented disposition. Do not create a second active credential just because the target platform accepted a row.
Define the migration before choosing a tool
Teams often use the word migration for several different jobs. Name the job first because each one changes the acceptable source data, target state and rollback plan.
| Migration job | Primary decision | Keep with the existing owner |
|---|---|---|
| Vendor-to-vendor platform cutover | How existing issuer records become valid target-platform records | This guide |
| Paper or PDF digitization | Whether a legacy document supports a new digital claim | Digital credential guide |
| Open Badges version upgrade | How a badge changes from one standards representation to another | Open Badges 3.0 guide |
| Holder wallet move | Whether a holder can store or present an existing credential elsewhere | Digital credential wallet guide |
| Platform selection | Which product meets the current program requirements | Digital credentialing platforms guide |
This ownership boundary prevents a migration project from silently changing the award criteria, issuer authority or credential standard while moving data.
Set continuity outcomes before exporting data
Write acceptance statements that a program owner, support lead and technical operator can test. At minimum, decide what should happen to the old public record, the new public record, the recipient notification and the internal audit trail.
Use language such as:
- Every source credential has one recorded migration disposition.
- A migrated credential preserves the approved claim and accountable issuer.
- A verifier can distinguish a current record from a superseded or historical
- A failed import does not trigger blind reissuance.
- A rollback restores the last known-good target cohort without rewriting the
one.
source history.
These are program controls, not promises that every platform supports the same status, redirect, wallet or import behavior.
Inventory the source program
Exporting a recipient list is not enough. Build a source inventory that joins the human-readable claim to the identifiers and governance evidence needed to interpret it.
| Source area | Minimum inventory | Migration question |
|---|---|---|
| Issuer | Legal or program name, responsible owner, public identity | Is the target issuer representation authorized and recognizable? |
| Credential definition | Title, criteria, description, skills, dates and version | Does the target record preserve the approved claim? |
| Recipient | Stable approved identifier and display fields | Can the operator match without exposing unnecessary personal data? |
| Award record | Source credential ID, issue date, expiry rule and current state | Is this record eligible to move or only to remain historical? |
| Evidence | References required to explain the award | Can evidence remain in its authoritative system? |
| Verification | Public URL, status behavior and support route | What will a verifier see before, during and after cutover? |
Sertifier’s current credential reports documentation describes the product reporting surface. Treat any export as an input to the inventory, then validate it against the program’s authoritative records.
Build a source-to-target field contract
Create a mapping table before importing a live recipient. Each source field needs a target field, a transformation rule, an owner and a failure action. Do not convert a missing value into an invented value to make an import pass.
The target contract should answer:
- Which identifier is stable across both systems?
- Which fields describe the credential definition rather than the recipient?
- Which dates are historical facts and which dates are target-system events?
- Which source status values have no exact target equivalent?
- Which links remain authoritative outside the credential platform?
The W3C Verifiable Credentials Data Model 2.0 separates an issuer, a credential subject and claims expressed by the credential. The 1EdTech Open Badges standard provides a standards context for badge credentials. A standard can guide field meaning and interoperability, but it does not approve the issuer’s migration policy.
Keep issuer identity and authority explicit
A new platform account does not create issuer authority. Record who approved the target issuer profile, which organization or program it represents and who can change it after cutover.
The existing credentials verification field guide owns the broader issuer-authenticity and governance explanation. For a migration, apply that principle to the cutover evidence: preserve the issuer name, public context, support route and accountable approver, then test how the new verification page presents them.
Decide the disposition of every source record
Not every source credential should become a new active credential. Assign one disposition before the migration run.
| Source state | Typical target disposition | Blocking question |
|---|---|---|
| Current and eligible | Create or import one matching current record | Does the program authorize a new platform record? |
| Expired | Preserve as historical or represent expiry accurately | Would a new issue date imply new validity? |
| Revoked, withdrawn or deleted | Keep out of normal issuance | Can the target represent the state without changing its meaning? |
| Duplicate | Reconcile to one approved record | Which identifier and authority determine the survivor? |
| Corrected | Move only the approved current version and retain traceability | Is the correction evidence complete? |
| Unknown | Hold for owner review | Who is allowed to resolve the uncertainty? |
Sertifier documents the behavior of an expiry date. Do not use expiry as a substitute for a different source status or a regulator’s decision.
Choose the target creation route
The right delivery method depends on volume, repeatability and the controls the program can operate. A small manual sample can validate the mapping. A bounded bulk upload can test a representative cohort. An API or automation path may be appropriate only after duplicate keys, retries and reconciliation are defined.
Sertifier’s current bulk sending guide documents a recipient-upload workflow. The public API documentation is the current reference for supported programmatic operations. The credentialing automation guide explains trigger, validation, duplicate and retry controls. Confirm the current product behavior for the chosen route before treating it as a migration capability.
Run a representative sample first
Use a sample that contains the states most likely to break the mapping. A sample made only of clean current records proves very little.
Include at least one current record, one expired record, one corrected identity, one duplicate candidate, one record with optional evidence and one unknown state. Review the stored target record before sending a notification. Then open the target verification page as a logged-out visitor.
Sertifier’s credential details guide and verification page documentation describe current product surfaces that can be used in this test. They do not replace the source program’s award decision.
Protect recipients from duplicate or confusing notifications
A migration can create a valid target record and still create a poor recipient experience. Decide whether recipients need a new email, whether the old URL will remain available and how support will explain the relationship between the two records.
Do not send a live migration email until the team has checked the sender identity, credential title, issue date, expiry display, verification route and support copy. The digital credential email delivery guide owns delivery acceptance and controlled resend. Migration owns only the decision about when a mapped record is ready to enter that delivery workflow.
Use a phased cutover with a rollback point
Cut over in independently reviewable cohorts. Keep a manifest for every run so the team can distinguish accepted, rejected, held and rolled-back records.
| Phase | Evidence to retain | Release gate |
|---|---|---|
| Inventory freeze | Source export ID, time, owner and checksum where available | Source scope is approved |
| Mapping test | Field contract and exception log | Required fields and states map correctly |
| Sample cohort | Source IDs, target IDs and screenshots or API responses | Logged-out verification passes |
| Limited production cohort | Run manifest, notification decision and reconciliation result | No unexplained duplicate or unknown state |
| Full cutover | Cohort manifests and owner approval | Support and verifier routes are ready |
| Closure | Final source disposition and retention decision | No source record is silently abandoned |
Rollback should remove or disable only the target records created by the failed cohort when the platform and policy permit it. It should not erase the source evidence or trigger a speculative second migration.
Apply least privilege to migration work
Limit export, mapping, import and issuance access to the people who need each step. Separate preparation from final release when practical, and record who approved the live cohort.
Sertifier’s current users and permissions documentation describes available product roles. Confirm the current permission model before granting access. Never place API keys, recipient exports or credential evidence in an unapproved repository or shared document.
Measure migration quality without inventing a success rate
Count outcomes from the run manifest, not from assumptions about the target platform. Useful measures include mapping acceptance, held records, duplicates prevented, verified target records, recipient delivery results and unresolved support cases.
| Measure | Numerator | Denominator | Decision it supports |
|---|---|---|---|
| Mapping acceptance | Records passing the field contract | Records attempted | Whether the mapping is ready to scale |
| Reconciliation completion | Resolved held or duplicate records | Records requiring review | Whether exceptions have accountable closure |
| Verification acceptance | Target records passing logged-out checks | Target records sampled | Whether public continuity is working |
| Delivery acceptance | Recipients reaching the intended access state | Notifications sent in the cohort | Whether communication is ready to expand |
| Unresolved continuity cases | Records without an approved source or target disposition | Records in scope | Whether cutover can close safely |
A low-volume sample is operational evidence, not proof of business impact. Organic acquisition remains a separate GSC measurement question, and product outcomes require verified analytics or CRM evidence.
Ask migration vendors for evidence
Before selecting a migration path, ask each vendor to demonstrate the exact workflow with representative records:
- Which source formats and fields are accepted?
- How are existing issue dates, expiry rules and external evidence handled?
- Can the platform preserve a source identifier without displaying it publicly?
- What happens when the same recipient and award appear twice?
- How are unknown, expired or corrected records represented?
- Can recipients and verifiers distinguish migrated records?
- Which reports or API responses support reconciliation?
- What happens to public verification after the commercial relationship ends?
The answer should be a testable behavior or current documentation, not a general portability claim.
Plan a controlled credential migration
Map your source records, target fields, exception states and verification continuity before moving a live cohort.
Frequently asked questions
Can we upload an old recipient CSV and call the migration complete?
No. A recipient list does not by itself preserve the credential definition, issuer authority, dates, state, evidence or verification history. Build and test the full mapping contract.
Should every legacy credential be reissued?
No. Eligibility depends on the source state and the program’s authority. Some records may remain historical, require review or be excluded from normal issuance.
Does Open Badges guarantee platform migration?
No. A standard can improve shared structure and interoperability, but the issuer still has to test field meaning, status behavior, evidence references, recipient access and verifier acceptance in the target implementation.
Can the old and new verification pages stay live together?
They can only if the program and platforms support a clear, non-conflicting experience. Define which page is current, how the relationship is explained and when the old route can close.
What should we migrate first?
Start with a small, representative cohort whose source authority and current state are well understood. Include difficult states before scaling.
