# Notary key rotation and migration There are several reasons why you may need to rotate the notary public keys, or migrate the current notary service to a new notary service: * To satisfy compliance and regulatory requirements, such as the Digital Operational Resilience Act (DORA). * To comply with cybersecurity policies within your institution. * To migrate from a hosted notary, such an IBM-hosted notary, to a SaaS notary service. To do this, we use a *chain-of-trust* process — we configure the new notary service so that it recognizes the public key of the old service, so that it can read the Merkle-tree data created by the old notary. This page describes the notary key rotation procedure, which involves the following steps: 1. Retrieve the old notary collections key from the current notary. 2. Configure the new notary service to recognize the old key, and then start it in standby mode. 3. Create an intent to migrate the public keys. 4. Migrate to the new notary by scaling down the old notary, and migrating the anti-rewind file to the new notary. The details are as follows: ## Retrieve the old notary collections public key The first step is to use the Ripple Custody API to retrieve the old notary collections public key from the system properties, so that we can register this key with the new notary. To do this: 1. Call the [List system properties](/products/custody/reference/api/openapi/systemproperties/getsystemproperties) operation, with query parameter `id=NOTARY_COLLECTIONS_KEY`. 2. Copy the `items[0].data.value.publicKey.value`. The response body is similar to the following: ```json { "items": [ { "data": { "id": "NOTARY_COLLECTIONS_KEY", "value": { "publicKey": { "value": "MCowBQYDK2VwAyEApXE1AfYVmeDN/0cAcNidEJ4IJGDwpL2MyFEb04c1F0A=", "type": "PublicKey" } }, "metadata": { "description": null, "revision": 1, "createdAt": "2025-07-14T12:23:44.653Z", "createdBy": { "id": "f0ca2fb4-369f-4617-aaa3-6a2f3370e931", "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1" }, "lastModifiedAt": "2025-07-14T12:23:44.653Z", "lastModifiedBy": { "id": "f0ca2fb4-369f-4617-aaa3-6a2f3370e931", "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1" }, "customProperties": {} }, "type": "NotaryCollectionsKeySystemProperty", "access": "ReadOnly" }, "signature": "", "signingKey": "" } ], "count": 1 } ``` ## Configure the new notary service and launch in standby mode The next step is to register the old notary key with the new notary, and launch it in standby mode. This generates all the new public keys for the collections, messaging, and API calls, that you need for the next step. To do this: 1. Insert the old public key into the new notary service, and start the service in standby mode. 2. Check the log files for the notary service. This will contain the following six items: * Migration key material * New trusted collections public key * New messaging public key * New API public key * Previous notary public key * Previous notary public key signature ## Create the key-migration intent The next step is to submit an intent to execute the key migration, using the information generated by the new notary. When you approve and sign this intent, this registers both the old and new public keys with Ripple Custody in preparation for restarting the new notary. To do this: 1. In the Custody API, call the [Propose an intent](/products/custody/reference/api/openapi/intents/createintent) operation with the `v0_AddTrustedPublicKeysForMigration` intent. (For more information about requesting intents, see [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals).) 2. Copy the log information retrieved above, into the six payload fields for the intent: * `newKeyMaterial` * `newCollectionSigningPublicKey` * `newMessageSigningPublicKey` * `newApiSigningPublicKey` * `currentCollectionSigningPublicKey` * `currentCollectionSigningPublicKeySignature` 3. Approve and sign the intent. To verify that these have been registered, you can call the following API operations: * [List trusted-collection public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeystrustedcollection) * [List api public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeysapi) * [List messaging public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeysmessages) Note: At this point the old notary is still active, and can continue to process intents using the current (old) public keys, until you are ready to migrate to the new notary. ## Migrate to the new notary When you are ready migrate to the new notary, the final step is to scale down the old notary, and use the Disaster Recovery procedure to recover the anti-rewind file (ARF), and launch the new notary in recovery mode. This recovers the state of the Ripple Custody system so that you can re-launch in regular operation mode. (For more information about the the anti-rewind file (ARF), see [Anti-rewind file](/products/custody/overview/security/data-integrity-and-audit-trail#anti-rewind-file-arf).) Note: Before migrating to the new notary, it is recommended to allow any intents in progress to complete. To migrate to the new notary, do this: 1. When ready to migrate, scale down the old notary instance. 2. Follow the Disaster recovery procedure described in [Recover your anti-rewind file](/products/custody/operations-and-maintenance/backup-and-restore/recover-anti-rewind-file) to generate a signed manifest for the anti-rewind file (ARF), and pass the manifest and signature to the notary. 3. Restart the notary in anti-rewind-file recovery mode to rebuild the ARF. 4. To verify, you can call any of the following API operations, and verify the publicKey and that the `revision` number is updated. * [List trusted-collection public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeystrustedcollection) * [List api public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeysapi) * [List messaging public keys](/products/custody/reference/api/openapi/trustedpublickeys/gettrustedpublickeysmessages) 1. Remove the `ANTI_REWIND_RECOVERY_*` environment variables and restart the notary again. The notary is now out of recovery mode and back in regular operation mode. Once migration is complete, the new notary operates as the active notary service.