Initiate account recovery for a user

You can initiate account recovery for users using the admin API endpoints. You can initiate the flow even for users that don't have a recovery address configured.

note

If the recovery flow initiated through the admin API expires, users without a recovery address can't start the flow again by themselves.

Read this document to learn more about the account recovery flow.

One-time codes

Ory Network

Send a request to the admin API of your project:

curl --request POST -sL \
  --header "Authorization: Bearer ORY_PAT" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
  "expires_in": "12h",
  "identity_id": "e01b5f2f-6afc-4194-8578-4cebcf69a4d5"
}' https://{your-project-slug}.projects.oryapis.com/admin/recovery/code

Golang code

package main

import (
    "context"
    "fmt"
    "io"

    ory "github.com/ory/client-go"
)

func main() {
    client := ory.NewAPIClient(&ory.Configuration{
        Servers: ory.ServerConfigurations{{
            URL: "https://{your-project-slug}.projects.oryapis.com",
        }},
        DefaultHeader: map[string]string{
            "Authorization": "Bearer ORY_PAT", // Personal access token for your Ory Network project
        },
    })

    code, res, err := client.V0alpha2Api.AdminCreateSelfServiceRecoveryCode(context.Background()).
        AdminCreateSelfServiceRecoveryCodeBody(*ory.NewAdminCreateSelfServiceRecoveryCodeBody("YOUR_IDENTITY_ID")).
        Execute()

    if err != nil {
        body, _ := io.ReadAll(res.Body)
        fmt.Printf("could not create recovery code %v: %v", err.Error(), string(body))
        panic(err)
    }

    fmt.Printf("Use link: %s\n", code.RecoveryLink)
    fmt.Printf("  With code: %s\n", code.RecoveryCode)
}

Self-hosted Ory Kratos

Run Ory Kratos easily on your local machine or server with the Ory Account Experience and default configuration in Docker:

git clone --depth 1 --branch master https://github.com/ory/kratos.git
cd kratos
git checkout master
git pull -ff
docker-compose -f quickstart.yml \
  -f contrib/quickstart/kratos/cloud/quickstart.yml up

Ory Kratos will then be avaiable at 127.0.0.1:4433 (public port) and 127.0.0.1:4434 (admin port).

And use it to create a recovery code:

curl --request POST -sL \
  --header "Content-Type: application/json" \
  --data '{
  "expires_in": "12h",
  "identity_id": "e01b5f2f-6afc-4194-8578-4cebcf69a4d5"
}' http://127.0.0.1:4434/recovery/code

Response

The response contains a recovery_link with the flow ID and a recovery_code. To recover the account, the user must access the link and enter the recovery code in the form available at the link.

{
  "recovery_link": "/ui/recovery?flow=79686c66-e427-4c1b-861e-083572f97964",
  "recovery_code": "76453943",
  "expires_at": "2022-10-25T03:09:37.60684766Z"
}

After successfully recovering their account, users can connect to a social sign-in provider or create a new password.

Magic links

To create the account recovery link, use:

Ory Network

Send a request to the admin API of your project:

curl --request POST -sL \
  --header "Authorization: Bearer ORY_PAT" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
  "expires_in": "12h",
  "identity_id": "e01b5f2f-6afc-4194-8578-4cebcf69a4d5"
}'  https://{your-project-slug}.projects.oryapis.com/admin/recovery/link

Golang code

package main

import (
    "context"
    "fmt"
    "io"

    ory "github.com/ory/client-go"
)

func main() {
    client := ory.NewAPIClient(&ory.Configuration{
        Servers: ory.ServerConfigurations{{
            URL: "https://{your-project-slug}.projects.oryapis.com",
        }},
        DefaultHeader: map[string]string{
            "Authorization": "Bearer ORY_PAT", // Personal access token for your Ory Network project
        },
    })

    link, res, err := client.V0alpha2Api.AdminCreateSelfServiceRecoveryLink(context.Background()).
        AdminCreateSelfServiceRecoveryLinkBody(*ory.NewAdminCreateSelfServiceRecoveryLinkBody("YOUR_INDENTITY_ID")).
        Execute()

    if err != nil {
        body, _ := io.ReadAll(res.Body)
        fmt.Printf("could not create recovery link %v: %v", err.Error(), string(body))
        panic(err)
    }

    fmt.Printf("Use link: %s\n", link.RecoveryLink)
}

Self-hosted Ory Kratos

Run Ory Kratos easily on your local machine or server with the Ory Account Experience and default configuration in Docker:

git clone --depth 1 --branch master https://github.com/ory/kratos.git
cd kratos
git checkout master
git pull -ff
docker-compose -f quickstart.yml \
  -f contrib/quickstart/kratos/cloud/quickstart.yml up

Ory Kratos will then be avaiable at 127.0.0.1:4433 (public port) and 127.0.0.1:4434 (admin port).

And use it to create a recovery link:

curl --request POST -sL \
  --header "Content-Type: application/json" \
  --data '{
  "expires_in": "12h",
  "identity_id": "e01b5f2f-6afc-4194-8578-4cebcf69a4d5"
}' http://127.0.0.1:4434/recovery/code

Response

The response contains a recovery_link with the flow ID and a random token. The user must access the link to recover the account. Upon accessing the link, the user can connect to a social sign-in provider or set up a new password.

{
  "recovery_link": "https://playground.projects.oryapis.com/self-service/recovery?flow=81c55cec-76fd-4907-bddf-cc112e835698&token=yM9nAZpPIjwccKh9qHRh8OfywZSRcr6q",
  "expires_at": "2022-02-25T03:09:37.60684766Z"
}

It is currently not possible to send the recovery link directly to a user's email, this feature is tracked as #595.