{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Rotate a Basic auth key"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"rotate-a-basic-auth-key","__idx":0},"children":["Rotate a Basic auth key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rotate a Basic auth access key by generating a replacement, updating your integration, verifying it works, and then revoking the old key. You can keep ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["up to two valid keys"]}," at the same time, so generating a replacement does not interrupt requests using the old key."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use OAuth when your integration supports it. This guide is for integrations that require Basic auth; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/direct-api-access-and-authentication"},"children":["Direct API Access and Authentication"]}," for the available authentication methods."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign in to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.resolvepay.com/dashboard/integrations"},"children":["Merchant Dashboard Integrations page"]}," with permission to change Direct API settings. Your merchant must have Direct API access."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Direct API"]}," section and confirm ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Enable Basic auth"]}," is on. Keep it enabled throughout the rotation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Identify every application, worker, scheduled job, and environment using the old key. Arrange access to their secret stores and deployment settings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that there is an available key slot. If two keys are already valid, identify a key that is no longer used before revoking it to free a slot. Do not revoke a key that still serves an integration."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Basic auth, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client ID"]}," is your merchant ID (the username), and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret"]}," is the access key (the password). The Client ID stays the same when you rotate a key. These are not OAuth credentials, and you do not select OAuth scopes for Basic auth keys."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Screenshots below show the actual dashboard components with fictional example credentials."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-generate-a-replacement","__idx":2},"children":["1. Generate a replacement"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate Basic auth access key"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter a recognizable name, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Warehouse API"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally select an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Expiration date"]},". A selected date expires at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["00:00 UTC at the start of that day"]},", not at the end. Choose a date that leaves enough time for the cutover. Leaving the date blank makes the key valid until revoked."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-auth-generate.fcc0515a068000e6b22cc7ae7bc744e87985ec6b65269feb8d891dceca04899d.9bb1daa4.png","alt":"Generate a Basic auth access key with a name and an optional expiration date"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The existing key continues working. An older key may appear as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Original credential"]}," in the list. You do not need to retrieve its secret to generate a replacement. New merchants start without an automatically generated Basic auth key; generate a first key before configuring an integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-save-the-new-secret","__idx":3},"children":["2. Save the new secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save your new Basic auth access key"]},", copy the Client ID and Client Secret into your integration's secure secret store. Use the secret field's copy control; the eye control lets you reveal it when needed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The new secret is available only in this confirmation. Once you close it, neither you nor Resolve can retrieve it again."]}," Do not put it in source control, screenshots, support messages, or logs. Close the confirmation only after saving it securely."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-auth-save.895655160583224989c0a27796ac04a945b547a9338535b75000bab05dd32ecd.9bb1daa4.png","alt":"One-time confirmation with the example client secret masked"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you close the confirmation without saving the secret, revoke that unused new key and generate another. Revoking the unused replacement leaves the old key working."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-update-and-verify-every-integration","__idx":4},"children":["3. Update and verify every integration"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replace the old password/Client Secret in each integration's secret store. Keep the existing username/Client ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deploy or restart applications and workers as required for them to load the replacement."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Make a normal API request using the replacement and confirm it succeeds. Check each consumer, including jobs that run infrequently."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check your application's request/error logs for authentication failures. Keep secrets and Authorization headers out of logs."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-auth-overlap.f792a833b2a963557a9176caee7ac7948ed4967914435f6d83784159d364f207.9bb1daa4.png","alt":"The original and replacement keys are both active during the cutover"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The dashboard's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Last used"]}," column can help identify activity, but a timestamp alone does not prove every consumer has switched. Usage timestamps are recorded at most once per minute, and the displayed list updates when you load the page or submit a key-management action. Reload the page to see updated metadata."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not revoke the old key until all consumers have successfully switched to the replacement."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-revoke-the-old-key","__idx":5},"children":["4. Revoke the old key"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the old key's row, open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["three-dot actions menu"]}," and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Revoke"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that you selected the old key, not the replacement."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the impact warning, then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Revoke access key"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-auth-revoke.ea639025f89ac384fe3d06c219e6c6d306ca2c5fbf1fef8f387320b89a596739.9bb1daa4.png","alt":"Revoke confirmation warning that requests using the old key will stop working"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Revocation takes effect immediately and cannot be undone."]}," Subsequent requests using the old key fail authentication; the replacement remains valid. The Client ID remains visible in the table."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirm your integration still succeeds with the replacement after revocation. If you have a controlled test using the old key, it should now receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Existing Shopify and BigCommerce connections remain linked after revocation. Establishing a new connection requires a valid credential."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-remove-the-revoked-entry-optional","__idx":6},"children":["5. Remove the revoked entry (optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open the revoked key's three-dot menu, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete"]},", and confirm ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete access key"]},". Deleting it does not restore access or undo revocation. An expired key must also be revoked before it can be deleted."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":7},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to check"},"children":["What to check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generate is unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check Direct API permissions and the two-valid-key limit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The replacement receives ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the merchant Client ID, the saved secret, Basic auth enablement, and whether the key has expired or been revoked."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A consumer fails after revocation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update that consumer to the saved replacement secret. The old key cannot be reactivated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The replacement secret was lost"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Revoke the unusable key and generate another; a closed confirmation cannot be reopened to recover its secret."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["There is no expiration date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]}," in the Expires column means the key has no scheduled expiration. It remains valid until revoked."]}]}]}]}]}]},"headings":[{"value":"Rotate a Basic auth key","id":"rotate-a-basic-auth-key","depth":1},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"1. Generate a replacement","id":"1-generate-a-replacement","depth":2},{"value":"2. Save the new secret","id":"2-save-the-new-secret","depth":2},{"value":"3. Update and verify every integration","id":"3-update-and-verify-every-integration","depth":2},{"value":"4. Revoke the old key","id":"4-revoke-the-old-key","depth":2},{"value":"5. Remove the revoked entry (optional)","id":"5-remove-the-revoked-entry-optional","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"Rotate a Basic auth key"}},"lastModified":"2026-11-03T18:37:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/rotate-a-basic-auth-key","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}