---
title: "Update Recovery Flow"
method: POST
path: "/self-service/recovery"
tags: ["frontend"]
---

# Update Recovery Flow

`POST /self-service/recovery`

Use this endpoint to update a recovery flow. This endpoint
behaves differently for API and browser flows and has several states:

`choose_method` expects `flow` (in the URL query) and `email` (in the body) to be sent
and works with API- and Browser-initiated flows.
For API clients and Browser clients with HTTP Header `Accept: application/json` it either returns a HTTP 200 OK when the form is valid and HTTP 400 OK when the form is invalid.
and a HTTP 303 See Other redirect with a fresh recovery flow if the flow was otherwise invalid (e.g. expired).
For Browser clients without HTTP Header `Accept` or with `Accept: text/*` it returns a HTTP 303 See Other redirect to the Recovery UI URL with the Recovery Flow ID appended.
`sent_email` is the success state after `choose_method` for the `link` method and allows the user to request another recovery email. It
works for both API and Browser-initiated flows and returns the same responses as the flow in `choose_method` state.
`passed_challenge` expects a `token` to be sent in the URL query and given the nature of the flow ("sending a recovery link")
does not have any API capabilities. The server responds with a HTTP 303 See Other redirect either to the Settings UI URL
(if the link was valid) and instructs the user to update their password, or a redirect to the Recover UI URL with
a new Recovery Flow ID which contains an error message that the recovery link was invalid.

More information can be found at [Ory Kratos Account Recovery Documentation](../self-service/flows/account-recovery).

## Query parameters

- `flow` string, required
- `token` string

## Headers

- `Cookie` string

## Request body

- union — Update Recovery Flow Request Body
  - UpdateRecoveryFlowWithLinkMethod — Update Recovery Flow with Link Method
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `email` string, required — Email to Recover Needs to be set when initiating the flow. If the email is a registered recovery email, a recovery link will be sent. If the email is not known, an email with details on what happened will be sent instead. format: email
    - `method` 'link' | 'code', required — Method is the method that should be used for this recovery flow Allowed values are `link` and `code` link RecoveryStrategyLink code RecoveryStrategyCode
    - `transient_payload` object — Transient data to pass along to any webhooks
  - UpdateRecoveryFlowWithCodeMethod — Update Recovery Flow with Code Method
    - `code` string — Code from the recovery email If you want to submit a code, use this field, but make sure to _not_ include the email field, as well.
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `email` string — The email address of the account to recover If the email belongs to a valid account, a recovery email will be sent. If you want to notify the email address if the account does not exist, see the [notify_unknown_recipients flag](https://www.ory.sh/docs/kratos/self-service/flows/account-recovery-password-reset#attempted-recovery-notifications) If a code was already sent, including this field in the payload will invalidate the sent code and re-send a new code. format: email
    - `method` 'link' | 'code', required — Method is the method that should be used for this recovery flow Allowed values are `link` and `code`. link RecoveryStrategyLink code RecoveryStrategyCode
    - `recovery_address` string — A recovery address that is registered for the user. It can be an email, a phone number (to receive the code via SMS), etc. Used in RecoveryV2.
    - `recovery_confirm_address` string — If there are multiple recovery addresses registered for the user, and the initially provided address is different from the address chosen when the choice (of masked addresses) is presented, then we need to make sure that the user actually knows the full address to avoid information exfiltration, so we ask for the full address. Used in RecoveryV2.
    - `recovery_select_address` string — If there are multiple addresses registered for the user, a choice is presented and this field stores the result of this choice. Addresses are 'masked' (never sent in full to the client and shown partially in the UI) since at this point in the recovery flow, the user has not yet proven that it knows the full address and we want to avoid information exfiltration. So for all intents and purposes, the value of this field should be treated as an opaque identifier. Used in RecoveryV2.
    - `screen` string — Set to "previous" to go back in the flow, meaningfully. Used in RecoveryV2.
    - `transient_payload` object — Transient data to pass along to any webhooks

## Response `200`

recoveryFlow

- RecoveryFlow — This request is used when an identity wants to recover their account. We recommend reading the [Account Recovery Documentation](../self-service/flows/password-reset-account-recovery)
  - `active` string — Active, if set, contains the recovery method that is being used. It is initially not set.
  - `continue_with` ContinueWith[] — Contains possible actions that could follow this flow
    - union
      - object — Indicates, that the UI flow could be continued by showing a verification ui
        - `action` 'show_verification_ui', required — Action will always be `show_verification_ui` show_verification_ui ContinueWithActionShowVerificationUIString
        - `flow` ContinueWithVerificationUiFlow, required
          - `id` string, uuid, required — The ID of the verification flow
          - `url` string — The URL of the verification flow If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
          - `verifiable_address` string, required — The address that should be verified in this flow
      - object — Indicates that a session was issued, and the application should use this token for authenticated requests
        - `action` 'set_ory_session_token', required — Action will always be `set_ory_session_token` set_ory_session_token ContinueWithActionSetOrySessionTokenString
        - `ory_session_token` string, required — Token is the token of the session
      - object — Indicates, that the UI flow could be continued by showing a settings ui
        - `action` 'show_settings_ui', required — Action will always be `show_settings_ui` show_settings_ui ContinueWithActionShowSettingsUIString
        - `flow` ContinueWithSettingsUiFlow, required
          - `id` string, uuid, required — The ID of the settings flow
          - `url` string — The URL of the settings flow If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
      - object — Indicates, that the UI flow could be continued by showing a recovery ui
        - `action` 'show_recovery_ui', required — Action will always be `show_recovery_ui` show_recovery_ui ContinueWithActionShowRecoveryUIString
        - `flow` ContinueWithRecoveryUiFlow, required
          - `id` string, uuid, required — The ID of the recovery flow
          - `url` string — The URL of the recovery flow If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
      - object — Indicates, that the UI flow could be continued by showing a recovery ui
        - `action` 'redirect_browser_to', required — Action will always be `redirect_browser_to` redirect_browser_to ContinueWithActionRedirectBrowserToString
        - `redirect_browser_to` string, required — The URL to redirect the browser to
  - `expires_at` string, date-time, required — ExpiresAt is the time (UTC) when the request expires. If the user still wishes to update the setting, a new request has to be initiated.
  - `id` string, uuid, required — ID represents the request's unique ID. When performing the recovery flow, this represents the id in the recovery ui's query parameter: http://<selfservice.flows.recovery.ui_url>?request=<id>
  - `issued_at` string, date-time, required — IssuedAt is the time (UTC) when the request occurred.
  - `request_url` string, required — RequestURL is the initial URL that was requested from Ory Kratos. It can be used to forward information contained in the URL's path or query for example.
  - `return_to` string — ReturnTo contains the requested return_to URL.
  - `state` unknown, required
  - `transient_payload` object — TransientPayload is used to pass data from the recovery flow to hooks and email templates
  - `type` string, required — The flow type can either be `api` or `browser`.
  - `ui` UiContainer, required — Container represents a HTML Form. The container can work with both HTTP Form and JSON requests
    - `action` string, required — Action should be used as the form action URL `<form action="{{ .Action }}" method="post">`.
    - `messages` UiText[]
      - `context` object — The message's context. Useful when customizing messages.
      - `id` integer, required
      - `text` string, required — The message text. Written in american english.
      - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
    - `method` string, required — Method is the form method (e.g. POST)
    - `nodes` UiNode[], required
      - `attributes` union, required
        - UiNodeInputAttributes — InputAttributes represents the attributes of an input node
          - `autocomplete` 'email' | 'tel' | 'url' | 'current-password' | 'new-password' | 'one-time-code' | 'username webauthn' — The autocomplete attribute for the input. email InputAttributeAutocompleteEmail tel InputAttributeAutocompleteTel url InputAttributeAutocompleteUrl current-password InputAttributeAutocompleteCurrentPassword new-password InputAttributeAutocompleteNewPassword one-time-code InputAttributeAutocompleteOneTimeCode username webauthn InputAttributeAutocompleteUsernameWebauthn
          - `disabled` boolean, required — Sets the input's disabled field to true or false.
          - `label` UiText
            - `context` object — The message's context. Useful when customizing messages.
            - `id` integer, required
            - `text` string, required — The message text. Written in american english.
            - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
          - `maxlength` integer — MaxLength may contain the input's maximum length.
          - `name` string, required — The input's element name.
          - `node_type` 'input', required — NodeType represents this node's types. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "input". text Text input Input img Image a Anchor script Script div Division
          - `onclick` string — OnClick may contain javascript which should be executed on click. This is primarily used for WebAuthn. Deprecated: Using OnClick requires the use of eval() which is a security risk. Use OnClickTrigger instead.
          - `onclickTrigger` 'oryWebAuthnRegistration' | 'oryWebAuthnLogin' | 'oryPasskeyLogin' | 'oryPasskeyLoginAutocompleteInit' | 'oryPasskeyRegistration' | 'oryPasskeySettingsRegistration' — OnClickTrigger may contain a WebAuthn trigger which should be executed on click. The trigger maps to a JavaScript function provided by Ory, which triggers actions such as PassKey registration or login. oryWebAuthnRegistration WebAuthnTriggersWebAuthnRegistration oryWebAuthnLogin WebAuthnTriggersWebAuthnLogin oryPasskeyLogin WebAuthnTriggersPasskeyLogin oryPasskeyLoginAutocompleteInit WebAuthnTriggersPasskeyLoginAutocompleteInit oryPasskeyRegistration WebAuthnTriggersPasskeyRegistration oryPasskeySettingsRegistration WebAuthnTriggersPasskeySettingsRegistration
          - `onload` string — OnLoad may contain javascript which should be executed on load. This is primarily used for WebAuthn. Deprecated: Using OnLoad requires the use of eval() which is a security risk. Use OnLoadTrigger instead.
          - `onloadTrigger` 'oryWebAuthnRegistration' | 'oryWebAuthnLogin' | 'oryPasskeyLogin' | 'oryPasskeyLoginAutocompleteInit' | 'oryPasskeyRegistration' | 'oryPasskeySettingsRegistration' — OnLoadTrigger may contain a WebAuthn trigger which should be executed on load. The trigger maps to a JavaScript function provided by Ory, which triggers actions such as PassKey registration or login. oryWebAuthnRegistration WebAuthnTriggersWebAuthnRegistration oryWebAuthnLogin WebAuthnTriggersWebAuthnLogin oryPasskeyLogin WebAuthnTriggersPasskeyLogin oryPasskeyLoginAutocompleteInit WebAuthnTriggersPasskeyLoginAutocompleteInit oryPasskeyRegistration WebAuthnTriggersPasskeyRegistration oryPasskeySettingsRegistration WebAuthnTriggersPasskeySettingsRegistration
          - `pattern` string — The input's pattern.
          - `required` boolean — Mark this input field as required.
          - `type` 'text' | 'password' | 'number' | 'checkbox' | 'hidden' | 'email' | 'tel' | 'submit' | 'button' | 'datetime-local' | 'date' | 'url', required — The input's element type. text InputAttributeTypeText password InputAttributeTypePassword number InputAttributeTypeNumber checkbox InputAttributeTypeCheckbox hidden InputAttributeTypeHidden email InputAttributeTypeEmail tel InputAttributeTypeTel submit InputAttributeTypeSubmit button InputAttributeTypeButton datetime-local InputAttributeTypeDateTimeLocal date InputAttributeTypeDate url InputAttributeTypeURI
          - `value` unknown
        - UiNodeTextAttributes
          - `id` string, required — A unique identifier
          - `node_type` 'text', required — NodeType represents this node's types. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "text". text Text input Input img Image a Anchor script Script div Division
          - `text` UiText, required
            - `context` object — The message's context. Useful when customizing messages.
            - `id` integer, required
            - `text` string, required — The message text. Written in american english.
            - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
        - UiNodeImageAttributes
          - `height` integer, required — Height of the image
          - `id` string, required — A unique identifier
          - `node_type` 'img', required — NodeType represents this node's types. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "img". text Text input Input img Image a Anchor script Script div Division
          - `src` string, required — The image's source URL. format: uri
          - `width` integer, required — Width of the image
        - UiNodeAnchorAttributes
          - `href` string, required — The link's href (destination) URL. format: uri
          - `id` string, required — A unique identifier
          - `node_type` 'a', required — NodeType represents this node's types. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "a". text Text input Input img Image a Anchor script Script div Division
          - `title` UiText, required
            - `context` object — The message's context. Useful when customizing messages.
            - `id` integer, required
            - `text` string, required — The message text. Written in american english.
            - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
        - UiNodeScriptAttributes
          - `async` boolean, required — The script async type
          - `crossorigin` string, required — The script cross origin policy
          - `id` string, required — A unique identifier
          - `integrity` string, required — The script's integrity hash
          - `node_type` 'script', required — NodeType represents this node's types. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "script". text Text input Input img Image a Anchor script Script div Division
          - `nonce` string, required — Nonce for CSP A nonce you may want to use to improve your Content Security Policy. You do not have to use this value but if you want to improve your CSP policies you may use it. You can also choose to use your own nonce value!
          - `referrerpolicy` string, required — The script referrer policy
          - `src` string, required — The script source
          - `type` string, required — The script MIME type
        - UiNodeDivisionAttributes — Division sections are used for interactive widgets that require a hook in the DOM / view.
          - `class` string — A classname that should be rendered into the DOM.
          - `data` object — Data is a map of key-value pairs that are passed to the division. They may be used for `data-...` attributes.
          - `id` string, required — A unique identifier
          - `node_type` 'div', required — NodeType represents this node's type. It is a mirror of `node.type` and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "script". text Text input Input img Image a Anchor script Script div Division
      - `group` 'default' | 'password' | 'oidc' | 'profile' | 'link' | 'code' | 'totp' | 'lookup_secret' | 'webauthn' | 'passkey' | 'identifier_first' | 'captcha' | 'saml', required — Group specifies which group (e.g. password authenticator) this node belongs to. default DefaultGroup password PasswordGroup oidc OpenIDConnectGroup profile ProfileGroup link LinkGroup code CodeGroup totp TOTPGroup lookup_secret LookupGroup webauthn WebAuthnGroup passkey PasskeyGroup identifier_first IdentifierFirstGroup captcha CaptchaGroup saml SAMLGroup
      - `messages` UiText[], required
        - `context` object — The message's context. Useful when customizing messages.
        - `id` integer, required
        - `text` string, required — The message text. Written in american english.
        - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
      - `meta` UiNodeMeta, required — This might include a label and other information that can optionally be used to render UIs.
        - `label` UiText
          - `context` object — The message's context. Useful when customizing messages.
          - `id` integer, required
          - `text` string, required — The message text. Written in american english.
          - `type` 'info' | 'error' | 'success', required — The message type. info Info error Error success Success
      - `type` 'text' | 'input' | 'img' | 'a' | 'script' | 'div', required — The node's type text Text input Input img Image a Anchor script Script div Division

## Other responses

- `303` — Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 204.
- `400` — recoveryFlow
- `410` — errorGeneric
- `422` — errorBrowserLocationChangeRequired
- `default` — errorGeneric

---

[API](https://skmtc.net/ory/apis/ory-identities-api.md) · [All operations](https://skmtc.net/ory/apis/ory-identities-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ory/ory-identities-api/versions/7a0df90e2f13/schema)