Clarify recovery/verification API documentation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 161
- Forks
- 1.9k
- PR merge metrics
- No merged PRs in 30d
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the updateRecoveryFlow and updateVerificationFlow pages in the Ory API reference, then review the linked discussion for context. Compare the documented request fields and methods with the two-stage recovery and verification flows described in the issue. Done means the documentation clearly explains which fields and methods apply at each state.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100