Skip to main content

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.

Bodyrequired

    methodrequired

    Update Recovery Flow Request Body

    Possible values: [code, link]

    codestring

    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_tokenstring

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

    emailstring

    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

Responses​

recoveryFlow

Schema
    activestring

    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
    actionstringrequired

    Action will always be show_verification_ui show_verification_ui ContinueWithActionShowVerificationUIString

    Possible values: [show_verification_ui]

    flow objectrequired
    idstring<uuid>required

    The ID of the verification flow

    urlstring

    The URL of the verification flow

    verifiable_addressstringrequired

    The address that should be verified in this flow

  • ]
    • expires_atstring<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.

    idstring<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=

    issued_atstring<date-time>required

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

    request_urlstringrequired

    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_tostring

    ReturnTo contains the requested return_to URL.

    staterequired

    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.

    typeType is the flow type. (string)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

    actionstringrequired

    Action should be used as the form action URL <form action="{{ .Action }}" method="post">.

    messages object[]
  • Array [
    • contextobject

    The message's context. Useful when customizing messages.

    idinteger<int64>required
    textstringrequired

    The message text. Written in american english.

    typestringrequired

    The message type. info Info error Error success Success

    Possible values: [info, error, success]

  • ]
    • methodstringrequired

    Method is the form method (e.g. POST)

    nodes object[]required
  • Array [
    • attributes objectrequired
    node_typerequired

    Possible values: [a, img, input, script, text]

    hrefstringrequired

    The link's href (destination) URL.

    format: uri

    idstringrequired

    A unique identifier

    title objectrequired
    contextobject

    The message's context. Useful when customizing messages.

    idinteger<int64>required
    textstringrequired

    The message text. Written in american english.

    typestringrequired

    The message type. info Info error Error success Success

    Possible values: [info, error, success]

    groupstringrequired

    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

    Possible values: [default, password, oidc, profile, link, code, totp, lookup_secret, webauthn]

    messages object[]required
  • Array [
    • contextobject

    The message's context. Useful when customizing messages.

    idinteger<int64>required
    textstringrequired

    The message text. Written in american english.

    typestringrequired

    The message type. info Info error Error success Success

    Possible values: [info, error, success]

  • ]
    • meta objectrequired

    This might include a label and other information that can optionally be used to render UIs.

    label object
    contextobject

    The message's context. Useful when customizing messages.

    idinteger<int64>required
    textstringrequired

    The message text. Written in american english.

    typestringrequired

    The message type. info Info error Error success Success

    Possible values: [info, error, success]

    typestringrequired

    The node's type text Text input Input img Image a Anchor script Script

    Possible values: [text, input, img, a, script]

  • ]
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://accounts.<domain>/auth/self-service/recovery");
request.Headers.Add("Accept", "application/json");
var content = new StringContent("{\n  \"csrf_token\": \"string\",\n  \"email\": \"string\",\n  \"method\": \"link\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://accounts.<domain>
Parameters
— queryrequired
— query
— header
Body required
{
  "csrf_token": "string",
  "email": "string",
  "method": "link"
}