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.

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 API

Send a request to the Admin API of your project. This operation requires an API Key.

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

tip

Read Authorization with API Keys to learn more about API Keys in the Ory Network.

Go SDK

package main

import (
	"context"
	"fmt"
	"io"

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

func main() {
	client := ory.NewAPIClient(&ory.Configuration{
		Servers: ory.ServerConfigurations{{
			URL: "https://$PROJECT_SLUG.projects.oryapis.com",
		}},
		DefaultHeader: map[string]string{
			"Authorization": "Bearer ORY_API_KEY", // API Key for your Ory Network project
		},
	})

	code, res, err := client.FrontendApi.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)
}

tip

This code requires an API Key. Read Authorization with API Keys to learn more about API Keys in the Ory Network.

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 API

Send a request to the Admin API of your project. This operation requires an API Key.

curl --request POST -sL \
   --header "Authorization: Bearer {ORY_API_KEY}" \
   --header "Content-Type: application/json" \
   --data '{
   "expires_in": "12h",
   "identity_id": "$ACCOUNT_ID"
   }' https://$PROJECT_SLUG.projects.oryapis.com/admin/recovery/link

tip

Read Authorization with API Keys to learn more about API Keys in the Ory Network.

Go SDK

package main

import (
	"context"
	"fmt"
	"io"

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

func main() {
	client := ory.NewAPIClient(&ory.Configuration{
		Servers: ory.ServerConfigurations{{
			URL: "https://$PROJECT_SLUG.projects.oryapis.com",
		}},
		DefaultHeader: map[string]string{
			"Authorization": "Bearer ORY_API_KEY", // API Key for your Ory Network project
		},
	})

	link, res, err := client.FrontendApi.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)
}

tip

This code requires an API Key. Read Authorization with API Keys to learn more about API Keys in the Ory Network.

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.