docs(auth): clarify OTP migration steps - #799
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
| During the rollout, exact-type policies must allow the legacy activity types and | ||
| the updated `INIT_OTP_V3`, `VERIFY_OTP_V2`, and `OTP_LOGIN_V2` activity types. | ||
| Keep `CREATE_SUB_ORGANIZATION_V7` allowed because it accepts both token types. | ||
| This does not make activity versions interchangeable within one OTP attempt. |
There was a problem hiding this comment.
potentially ambiguous here?
There was a problem hiding this comment.
Is the sentence needed at all? I wouldn't have assumed they'd be interchangeable but maybe I'm missing something.
| `ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7` accepts both legacy verification | ||
| tokens and the enclave-issued tokens from `VERIFY_OTP_V2`. Migrate customers | ||
| to the encrypted flow while continuing to use V7. `ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V8` | ||
| accepts only enclave-issued tokens and is not required for this migration. |
There was a problem hiding this comment.
minor: could clarify this language
There was a problem hiding this comment.
yeah I think this is a tiny bit confusing. we are saying that they have to use the encrypted flow but do not have to migrate to v8. maybe a crisper sentence on that?
| Keep `CREATE_SUB_ORGANIZATION_V7` allowed because it accepts both token types. | ||
| This does not make activity versions interchangeable within one OTP attempt. | ||
|
|
||
| Prefer `activity.kind` when the same policy must cover every version of a |
There was a problem hiding this comment.
I'm not sure this works - all OTP versions map to the same kind, right? We should recommend exact current types for this migration:
ACTIVITY_TYPE_INIT_OTP_V3
ACTIVITY_TYPE_VERIFY_OTP_V2
ACTIVITY_TYPE_OTP_LOGIN_V2
ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7
| During a staged rollout, exact-type policies must allow both legacy and updated versions until all clients and servers use the new flow. This does not make the activity versions interchangeable within an OTP attempt. Prefer `activity.kind` when the same policy should cover every version of a specific activity: | ||
| During the rollout, exact-type policies must allow the legacy activity types and | ||
| the updated `INIT_OTP_V3`, `VERIFY_OTP_V2`, and `OTP_LOGIN_V2` activity types. | ||
| Keep `CREATE_SUB_ORGANIZATION_V7` allowed because it accepts both token types. |
There was a problem hiding this comment.
I think this could use a working example of how verificationToken should be used properly in v7
| 1. Update exact-version policies. See [Update policies before deploying](#update-policies-before-deploying). | ||
| 2. Upgrade the frontend and backend Turnkey packages together. | ||
| 3. Update the OTP flow. Keep each OTP attempt's bundle, token, and client key together. | ||
| 4. Send the OTP code to the backend only in `encryptedOtpBundle`. |
There was a problem hiding this comment.
I'd rephrase this: "Plaintext OTP material must remain on the client; any application-server request must carry only encryptedOtpBundle"
| - Update policies before deploying updated SDKs. | ||
| - Upgrade the frontend and backend Turnkey packages together. | ||
| - Store `otpId`, `otpEncryptionTargetBundle`, and the client key as state for one OTP attempt. | ||
| - On resend, replace all attempt state rather than reusing an old bundle or key. |
There was a problem hiding this comment.
I don't think you meant to delete this? Should modify to say something like "On resend, replace the otpId, encryption target bundle, and verification key together"
| 4. Send the OTP code to the backend only in `encryptedOtpBundle`. | ||
| 5. Test email and SMS separately, if your application supports both. | ||
| 6. Test an existing-user login and a new-user signup before deployment. | ||
| 7. Deploy the updated client and backend together. |
There was a problem hiding this comment.
that probably would be an issues for mobile releases and cached web clients. Maybe say "deploy a backward-compatible backend first, roll out clients, monitor legacy activity usage, then remove compatibility and legacy policy types"
2 participants
Summary
Validation