Administrative account recovery
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.
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
- Golang code
- Self-hosted Ory Kratos
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
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)
}
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
- Golang code
- Self-hosted Ory Kratos
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
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)
}
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.