Clarify recovery/verification API documentation
Opened this issue · 1 comments
Preflight checklist
- I could not find a solution in the existing issues, docs, nor discussions.
- I agree to follow this project's Code of Conduct.
- I have read and am following this repository's Contribution Guidelines.
- This issue affects my Ory Network project.
- I have joined the Ory Community Slack.
- I am signed up to the Ory Security Patch Newsletter.
Describe your problem
The recovery API documentation shows all of the fields for the body on POST for all states.
https://www.ory.sh/docs/reference/api#tag/frontend/operation/updateRecoveryFlow
The verification API documentation doesn't even show the code method.
https://www.ory.sh/docs/reference/api#tag/frontend/operation/updateVerificationFlow
This might confuse some users since we don't indicate that the Recovery & Verification flows can have two states.
The recovery flow is submitted twice, once to get the email sent out to the email, and the second to submit the code sent out from the email.
The flow kind of looks a bit like this:
- Create recovery flow
- Submit email
- Re-render form based on response (or get flow data through ID)
- Submit code
- Get redirected to settings flow on success OR handle form error
Describe your ideal solution
We should update the description to indicate what is required when.
Not sure how we could show multiple states with the OpenAPI spec.
Workarounds or alternatives
None
Version
latest
Additional Context
https://github.com/orgs/ory/discussions/54#discussioncomment-5314981
Hey @Benehiko thank you for opening this. It will definitely help users who struggled with the two path ways i.e. email, then code like myself. It took me a while to understand this separation as nothing pointed to this in the docs.
For the verification code not showing that is also something I struggled with and documented part of an issue.
Many thanks for your help!