{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/governance/users/refresh-user-keys","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/governance/users/refresh-user-keys","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/governance/users/refresh-user-keys","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/governance/users/refresh-user-keys","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/governance/users/refresh-user-keys","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/governance/users/refresh-user-keys","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/governance/users/refresh-user-keys","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Refresh user keys","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"refresh-user-keys","__idx":0},"children":["Refresh user keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If there is a suspicion that private keys were compromised, lock the existing user and create a replacement user with new keys. You cannot replace a user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicKey"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_UpdateUser"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you refresh the user key, decide what kind of replacement user you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UI human user"]},": The user creates a new profile with the ","Ripple Custody"," authenticator app and shares the new public key. The replacement user should receive the original human-facing alias and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API or bot user"]},": Generate a new API key pair for the client or bot, then use the new public key when you create the replacement user. Store the new private key in your secrets manager."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the existing user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata.revision"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alias"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roles"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},". Also prepare:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A new UUID for the replacement user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A retired alias for the old user, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operator-retired-20260618@example.com"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retired ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," for the old user. Do not set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"; when present, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," must be an array of valid login ID objects."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/authentication/generate-api-keys-and-register"},"children":["Ripple Custody API > Generate a key pair and share the public key"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/authentication/ui-authentication#register-and-log-in"},"children":["Ripple Custody UI > Create a profile"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"refresh-a-user-key","__idx":2},"children":["Refresh a user key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These steps describe how to refresh a user key with the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To refresh a user key:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get the current user details."," ","For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/users/manage-users-and-roles#view-users-and-roles-with-the-api"},"children":["Manage users and roles"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_UpdateUser"]}," intent for the existing user that changes the old user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alias"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," to retired values. This releases the original alias and login IDs for the replacement user."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payload\": {\n    \"reference\": {\n      \"id\": \"61aaa805-f9b8-11eb-b158-dcfb48cfb3cb\",\n      \"revision\": 2\n    },\n    \"alias\": \"operator-retired-20260618@example.com\",\n    \"roles\": [\"transaction-operator\"],\n    \"loginIds\": [\n      {\n        \"id\": \"operator-retired-20260618@example.com\",\n        \"providerId\": \"harmonize\"\n      }\n    ],\n    \"description\": \"Retired user record after key refresh\",\n    \"customProperties\": {\n      \"keyRefreshStatus\": \"retired\"\n    },\n    \"type\": \"v0_UpdateUser\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user has multiple login providers, provide a retired ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," entry for each provider. Do not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_LockUser"]}," intent to lock the existing user."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payload\": {\n    \"reference\": {\n      \"id\": \"61aaa805-f9b8-11eb-b158-dcfb48cfb3cb\",\n      \"revision\": 3\n    },\n    \"type\": \"v0_LockUser\"\n  }\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a replacement user with a new user ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", the original alias and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},", the required roles, and the newly generated public key."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payload\": {\n    \"id\": \"4d8c6240-3261-4991-9aa9-59e66f089d76\",\n    \"alias\": \"operator@example.com\",\n    \"publicKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\",\n    \"roles\": [\"transaction-operator\"],\n    \"loginIds\": [\n      {\n        \"id\": \"operator@example.com\",\n        \"providerId\": \"harmonize\"\n      }\n    ],\n    \"lock\": \"Unlocked\",\n    \"description\": \"Replacement user after key refresh\",\n    \"customProperties\": {\n      \"replacesUserId\": \"61aaa805-f9b8-11eb-b158-dcfb48cfb3cb\"\n    },\n    \"type\": \"v0_CreateUser\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a UI human user, use the public key from the user's new authenticator profile. For an API or bot user, use the public key from the newly generated API key pair."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the intents execute, confirm that the old user is locked and that the replacement user can authenticate and perform the expected read-only operation before allowing state mutation work."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about submitting update, lock, and create-user intents, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/intents/manage-intents-and-approvals#submit-an-intent-with-the-api"},"children":["Manage intents and approvals"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/users/manage-users-and-roles#create-a-user-with-the-api"},"children":["Manage users and roles"]},"."]}]},"headings":[{"value":"Refresh user keys","id":"refresh-user-keys","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Refresh a user key","id":"refresh-a-user-key","depth":2}],"frontmatter":{"seo":{"title":"Refresh user keys"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/governance/users/refresh-user-keys","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}