ory / ory/docs

Clarify recovery/verification API documentation

Open
#1,321 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug feat
Dominant language
TypeScript
Stars
161
Forks
1.9k
PR merge metrics
No merged PRs in 30d

Description

Preflight checklist
Describe your problem

The recovery API documentation shows all of the fields for the body on POST for all states.

image

https://www.ory.sh/docs/reference/api#tag/frontend/operation/updateRecoveryFlow

The verification API documentation doesn't even show the code method.
image

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:

  1. Create recovery flow
  2. Submit email
  3. Re-render form based on response (or get flow data through ID)
  4. Submit code
  5. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.