Budibase/budibase · error · HTTPError

A new verification key is required when changing the embed S

Error message

A new verification key is required when changing the embed SSO algorithm

What it means

This HTTP 400 error is thrown by encodeConfigForStorage when saving an embed SSO configuration whose key field is the PASSWORD_REPLACEMENT sentinel (meaning 'keep the stored key') while the algorithm differs from the previously stored configuration. Verification keys are tied to their algorithm family (HMAC shared secret vs EC/RSA public key), so silently reusing the old key under a new algorithm would produce tokens that can never verify. The library forces the caller to supply an explicit new key when the algorithm changes.

Source

Thrown at packages/server/src/sdk/workspace/embedSSO/index.ts:44

  }
  return encryption.decrypt(value.slice(SECRET_ENCODING_PREFIX.length))
}

/**
 * Encrypt the secret before storage. When the incoming key is the password
 * replacement sentinel, the existing (already encrypted) key is preserved so
 * the masked value sent to the builder round-trips without overwriting it.
 */
export function encodeConfigForStorage(
  incoming: EmbedSSOConfig,
  existing?: EmbedSSOConfig
): EmbedSSOConfig {
  let key = incoming.key
  if (key === PASSWORD_REPLACEMENT) {
    // the stored key is tied to its algorithm (shared secret vs EC/RSA public
    // key), so it cannot be reused if the algorithm has changed
    if (existing && existing.algorithm !== incoming.algorithm) {
      throw new HTTPError(
        "A new verification key is required when changing the embed SSO algorithm",
        400
      )
    }
    key = existing?.key || ""
  } else {
    key = encodeSecret(key)
  }
  return { ...incoming, key }
}

/**
 * Mask the secret so the builder can display and edit the config without ever
 * receiving the real key.
 */
export function maskConfigForBuilder(config: EmbedSSOConfig): EmbedSSOConfig {
  return { ...config, key: config.key ? PASSWORD_REPLACEMENT : "" }
}

View on GitHub (pinned to a81a902e9a)

Solutions

Supply a fresh verification key in the request instead of the PASSWORD_REPLACEMENT placeholder when the algorithm is being changed
If the algorithm change was accidental, re-send the original algorithm along with the masked key so it round-trips
If you truly intend to keep the same key material, first fetch the existing config, decode the real key server-side, and submit it as an explicit new key
Split the update into two calls: one that only changes non-key fields with the masked key and same algorithm, then a second that sets the new algorithm together with the new key

Example fix

// before
await updateEmbedSSO({ ...existing, algorithm: "RS256", key: "••••••••" }) // masked placeholder, algorithm changed -> 400
// after
await updateEmbedSSO({ ...existing, algorithm: "RS256", key: newRs256PublicKeyPem })

Defensive patterns

Strategy: validation

Validate before calling

const changingAlgorithm = existing && incoming.algorithm !== existing.algorithm
if (changingAlgorithm && (!incoming.key || incoming.key === PASSWORD_REPLACEMENT)) {
  throw new Error("Provide a new verification key when changing the embed SSO algorithm")
}

Try / catch

try {
  await saveEmbedSSO(config)
} catch (err) {
  if (err instanceof HTTPError && err.status === 400 && /new verification key/.test(err.message)) {
    promptUserForNewKey()
  } else throw err
}

Prevention

Always submit a fresh key whenever the algorithm field changes
Never round-trip the PASSWORD_REPLACEMENT sentinel together with an algorithm change
When editing configs programmatically, load the existing config and only send masked keys when the algorithm is unchanged

When it happens

Trigger: Calling updateWorkspacePackage (via the workspace embed SSO save path) with an EmbedSSOConfig whose key is PASSWORD_REPLACEMENT while incoming.algorithm !== existing.algorithm, e.g. the builder UI round-trips the masked key but the user changed HS256 to RS256 in the same save.

Common situations: A user edits an embed SSO config in the builder and switches the signing algorithm while leaving the masked key field untouched; automation or API scripts that echo back the masked key placeholder from a GET and only change the algorithm field.

Related errors

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/487be0b80d75b035. Report an issue: GitHub.