Update Recovery Flow

POST 
https://accounts.<domain>/auth/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.

Request

Query Parameters

flow stringrequired

The Recovery Flow ID

The value for this parameter comes from flow URL Query parameter sent to your application (e.g. /recovery?flow=abcde).

token string

Recovery Token

The recovery token which completes the recovery request. If the token is invalid (e.g. expired) an error will be shown to the end-user.

This parameter is usually set in a link and not used by any direct API call.

Header Parameters

Cookie string

HTTP Cookies

When using the SDK in a browser app, on the server side you must include the HTTP Cookie Header sent by the client to your server here. This ensures that CSRF and session cookies are respected.

application/json

Body

required

oneOf

updateRecoveryFlowWithLinkMethod

csrf_token string

Sending the anti-csrf token is only required for browser login flows.

email stringrequired

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, a email with details on what happened will be sent instead.

format: email

method stringrequired

Possible values: [link, code]

Method is the method that should be used for this recovery flow

Allowed values are link and code link RecoveryStrategyLink code RecoveryStrategyCode

updateRecoveryFlowWithCodeMethod

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

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 stringrequired

Possible values: [link, code]

Method is the method that should be used for this recovery flow

Allowed values are link and code. link RecoveryStrategyLink code RecoveryStrategyCode

application/x-www-form-urlencoded

Body

required

oneOf

updateRecoveryFlowWithLinkMethod

csrf_token string

Sending the anti-csrf token is only required for browser login flows.

email stringrequired

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, a email with details on what happened will be sent instead.

format: email

method stringrequired

Possible values: [link, code]

Method is the method that should be used for this recovery flow

Allowed values are link and code link RecoveryStrategyLink code RecoveryStrategyCode

updateRecoveryFlowWithCodeMethod

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

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 stringrequired

Possible values: [link, code]

Method is the method that should be used for this recovery flow

Allowed values are link and code. link RecoveryStrategyLink code RecoveryStrategyCode

Responses

200

recoveryFlow

application/json

Schema

Schema

active string

Active, if set, contains the recovery method that is being used. It is initially not set.

continue_with object[]
Contains possible actions that could follow this flow
Array [
oneOf
continueWithVerificationUi
action stringrequired
Possible values: [show_verification_ui]
Action will always be show_verification_ui show_verification_ui ContinueWithActionShowVerificationUIString
flow objectrequired
id uuidrequired
The ID of the verification flow
url string
The URL of the verification flow
verifiable_address stringrequired
The address that should be verified in this flow
continueWithSetOrySessionToken
action stringrequired
Possible values: [set_ory_session_token]
ory_session_token stringrequired
Token is the token of the session
continueWithSettingsUi
action stringrequired
Possible values: [show_settings_ui]
Action will always be show_settings_ui show_settings_ui ContinueWithActionShowSettingsUIString
flow objectrequired
id uuidrequired
The ID of the settings flow
continueWithRecoveryUi
action stringrequired
Possible values: [show_recovery_ui]
Action will always be show_recovery_ui show_recovery_ui ContinueWithActionShowRecoveryUIString
flow objectrequired
id uuidrequired
The ID of the recovery flow
url string
The URL of the recovery flow
]
expires_at date-timerequired

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 uuidrequired

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=

issued_at date-timerequired

IssuedAt is the time (UTC) when the request occurred.

request_url stringrequired

RequestURL is the initial URL that was requested. 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 required

State represents the state of this request:

choose_method: ask the user to choose a method (e.g. recover account via email) sent_email: the email has been sent to the user passed_challenge: the request was successful and the recovery challenge was passed.

type Type is the flow type.required

The flow type can either be api or browser.

ui objectrequired
Container represents a HTML Form. The container can work with both HTTP Form and JSON requests
action stringrequired
Action should be used as the form action URL <form action="{{ .Action }}" method="post">.
messages object[]
Array [
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
]
method stringrequired
Method is the form method (e.g. POST)
nodes object[]required
Array [
attributes objectrequired
oneOf
uiNodeInputAttributes
autocomplete string
Possible values: [email, tel, url, current-password, new-password, one-time-code]
The autocomplete attribute for the input. email InputAttributeAutocompleteEmail tel InputAttributeAutocompleteTel url InputAttributeAutocompleteUrl current-password InputAttributeAutocompleteCurrentPassword new-password InputAttributeAutocompleteNewPassword one-time-code InputAttributeAutocompleteOneTimeCode
disabled booleanrequired
Sets the input's disabled field to true or false.
label object
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
name stringrequired
The input's element name.
node_type stringrequired
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".
onclick string
OnClick may contain javascript which should be executed on click. This is primarily used for WebAuthn.
pattern string
The input's pattern.
required boolean
Mark this input field as required.
type stringrequired
Possible values: [text, password, number, checkbox, hidden, email, tel, submit, button, datetime-local, date, url]
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 nullable
The input's value.
TextAttributes represents the attributes of a text node.
id stringrequired
A unique identifier
node_type stringrequired
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 objectrequired
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
ImageAttributes represents the attributes of an image node.
height int64required
Height of the image
id stringrequired
A unique identifier
node_type stringrequired
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".
src stringrequired
The image's source URL.
format: uri
width int64required
Width of the image
AnchorAttributes represents the attributes of an anchor node.
href stringrequired
The link's href (destination) URL.
format: uri
id stringrequired
A unique identifier
node_type stringrequired
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".
title objectrequired
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
ScriptAttributes represent script nodes which load javascript.
async booleanrequired
The script async type
crossorigin stringrequired
The script cross origin policy
id stringrequired
A unique identifier
integrity stringrequired
The script's integrity hash
node_type stringrequired
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".
nonce stringrequired
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 stringrequired
The script referrer policy
src stringrequired
The script source
type stringrequired
The script MIME type
group stringrequired
Possible values: [default, password, oidc, profile, link, code, totp, lookup_secret, webauthn]
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
messages object[]required
Array [
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
]
meta objectrequired
This might include a label and other information that can optionally be used to render UIs.
label object
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
type stringrequired
Possible values: [text, input, img, a, script]
The node's type text Text input Input img Image a Anchor script Script
]

Example (from schema)

{
  "active": "string",
  "continue_with": [
    {},
    {},
    {},
    {}
  ],
  "expires_at": "2025-04-17T12:10:30.816Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "issued_at": "2025-04-17T12:10:30.816Z",
  "request_url": "string",
  "return_to": "string",
  "type": "string",
  "ui": {
    "action": "string",
    "messages": [
      {
        "context": {},
        "id": 0,
        "text": "string",
        "type": "info"
      }
    ],
    "method": "string",
    "nodes": [
      {
        "attributes": {},
        "group": "default",
        "messages": [
          {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        ],
        "meta": {
          "label": {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        },
        "type": "text"
      }
    ]
  }
}

303

Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.

400

recoveryFlow

application/json

Schema

Schema

active string

Active, if set, contains the recovery method that is being used. It is initially not set.

continue_with object[]
Contains possible actions that could follow this flow
Array [
oneOf
continueWithVerificationUi
action stringrequired
Possible values: [show_verification_ui]
Action will always be show_verification_ui show_verification_ui ContinueWithActionShowVerificationUIString
flow objectrequired
id uuidrequired
The ID of the verification flow
url string
The URL of the verification flow
verifiable_address stringrequired
The address that should be verified in this flow
continueWithSetOrySessionToken
action stringrequired
Possible values: [set_ory_session_token]
ory_session_token stringrequired
Token is the token of the session
continueWithSettingsUi
action stringrequired
Possible values: [show_settings_ui]
Action will always be show_settings_ui show_settings_ui ContinueWithActionShowSettingsUIString
flow objectrequired
id uuidrequired
The ID of the settings flow
continueWithRecoveryUi
action stringrequired
Possible values: [show_recovery_ui]
Action will always be show_recovery_ui show_recovery_ui ContinueWithActionShowRecoveryUIString
flow objectrequired
id uuidrequired
The ID of the recovery flow
url string
The URL of the recovery flow
]
expires_at date-timerequired

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 uuidrequired

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=

issued_at date-timerequired

IssuedAt is the time (UTC) when the request occurred.

request_url stringrequired

RequestURL is the initial URL that was requested. 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 required

State represents the state of this request:

choose_method: ask the user to choose a method (e.g. recover account via email) sent_email: the email has been sent to the user passed_challenge: the request was successful and the recovery challenge was passed.

type Type is the flow type.required

The flow type can either be api or browser.

ui objectrequired
Container represents a HTML Form. The container can work with both HTTP Form and JSON requests
action stringrequired
Action should be used as the form action URL <form action="{{ .Action }}" method="post">.
messages object[]
Array [
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
]
method stringrequired
Method is the form method (e.g. POST)
nodes object[]required
Array [
attributes objectrequired
oneOf
uiNodeInputAttributes
autocomplete string
Possible values: [email, tel, url, current-password, new-password, one-time-code]
The autocomplete attribute for the input. email InputAttributeAutocompleteEmail tel InputAttributeAutocompleteTel url InputAttributeAutocompleteUrl current-password InputAttributeAutocompleteCurrentPassword new-password InputAttributeAutocompleteNewPassword one-time-code InputAttributeAutocompleteOneTimeCode
disabled booleanrequired
Sets the input's disabled field to true or false.
label object
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
name stringrequired
The input's element name.
node_type stringrequired
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".
onclick string
OnClick may contain javascript which should be executed on click. This is primarily used for WebAuthn.
pattern string
The input's pattern.
required boolean
Mark this input field as required.
type stringrequired
Possible values: [text, password, number, checkbox, hidden, email, tel, submit, button, datetime-local, date, url]
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 nullable
The input's value.
TextAttributes represents the attributes of a text node.
id stringrequired
A unique identifier
node_type stringrequired
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 objectrequired
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
ImageAttributes represents the attributes of an image node.
height int64required
Height of the image
id stringrequired
A unique identifier
node_type stringrequired
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".
src stringrequired
The image's source URL.
format: uri
width int64required
Width of the image
AnchorAttributes represents the attributes of an anchor node.
href stringrequired
The link's href (destination) URL.
format: uri
id stringrequired
A unique identifier
node_type stringrequired
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".
title objectrequired
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
ScriptAttributes represent script nodes which load javascript.
async booleanrequired
The script async type
crossorigin stringrequired
The script cross origin policy
id stringrequired
A unique identifier
integrity stringrequired
The script's integrity hash
node_type stringrequired
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".
nonce stringrequired
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 stringrequired
The script referrer policy
src stringrequired
The script source
type stringrequired
The script MIME type
group stringrequired
Possible values: [default, password, oidc, profile, link, code, totp, lookup_secret, webauthn]
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
messages object[]required
Array [
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
]
meta objectrequired
This might include a label and other information that can optionally be used to render UIs.
label object
context object
The message's context. Useful when customizing messages.
id int64required
text stringrequired
The message text. Written in american english.
type stringrequired
Possible values: [info, error, success]
The message type. info Info error Error success Success
type stringrequired
Possible values: [text, input, img, a, script]
The node's type text Text input Input img Image a Anchor script Script
]

Example (from schema)

{
  "active": "string",
  "continue_with": [
    {},
    {},
    {},
    {}
  ],
  "expires_at": "2025-04-17T12:10:30.817Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "issued_at": "2025-04-17T12:10:30.817Z",
  "request_url": "string",
  "return_to": "string",
  "type": "string",
  "ui": {
    "action": "string",
    "messages": [
      {
        "context": {},
        "id": 0,
        "text": "string",
        "type": "info"
      }
    ],
    "method": "string",
    "nodes": [
      {
        "attributes": {},
        "group": "default",
        "messages": [
          {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        ],
        "meta": {
          "label": {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        },
        "type": "text"
      }
    ]
  }
}

410

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

422

errorBrowserLocationChangeRequired

application/json

Schema

Schema

error object

The standard Ory JSON API error format.

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

redirect_browser_to string

Points to where to redirect the user to next.

Example (from schema)

{
  "error": {
    "error": {
      "code": 404,
      "debug": "SQL field \"foo\" is not a bool.",
      "details": {},
      "id": "string",
      "message": "The resource could not be found",
      "reason": "User with ID 1234 does not exist.",
      "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
      "status": "Not Found"
    }
  },
  "redirect_browser_to": "string"
}

default

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X POST 'https://accounts.<domain>/auth/self-service/recovery' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "csrf_token": "string",
  "email": "string",
  "method": "link"
}'

Request Collapse all

Base URL

https://accounts.<domain>

Parameters

flow — queryrequired

token — query

Cookie — header

Body required

Content-Type

application/jsonapplication/x-www-form-urlencoded

{
  "csrf_token": "string",
  "email": "string",
  "method": "link"
}