Skip to main content
The Recovery endpoints allow administrators to generate recovery codes and links that users can use to recover or activate their accounts.

​
Create a recovery code

curl -X POST https://{project}.projects.oryapis.com/admin/recovery/code \
  -H "Authorization: Bearer ory_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "a3b2c1d4-e5f6-7890-abcd-ef1234567890",
    "expires_in": "1h"
  }'
Generate a recovery code for an identity. This code can be used to recover or activate the account.

​
Request body

​
identity_id
string
required
UUID of the identity to create a recovery code for.
​
expires_in
string
How long the recovery code remains valid. Accepts duration formats like:
  • 1h (1 hour)
  • 30m (30 minutes)
  • 24h (24 hours)
  • 60s (60 seconds)
If not specified, defaults to the selfservice.methods.code.config.lifespan configuration value.
​
flow_type
string
The type of flow: api or browser. Determines the format of the recovery link.

​
Response

​
recovery_code
string
The recovery code that can be used to recover the account. Share this code with the user.
​
recovery_link
string
A URL to the recovery UI with an empty code field. The user must enter the recovery code at this URL.
​
expires_at
string
Timestamp (RFC3339 format) when the recovery code expires.

​
Example response

{
  "recovery_code": "123456",
  "recovery_link": "https://example.com/recovery?flow=abc-def-ghi",
  "expires_at": "2026-03-03T15:30:00Z"
}

​
Error responses

  • 400: Invalid request body or duration format
  • 404: Identity not found

​
Usage notes

Recovery codes are typically used when:
  • A user has lost access to their account
  • An administrator needs to activate a newly created account
  • A user needs to verify their email address
  • A passwordless onboarding flow is being used

​
Security considerations

  • Recovery codes are single-use only
  • Set appropriate expiration times based on your security requirements
  • Transmit codes through secure channels (encrypted email, SMS, etc.)
  • Never log or store recovery codes in plaintext
curl -X POST "https://{project}.projects.oryapis.com/admin/recovery/link?return_to=https://example.com/dashboard" \
  -H "Authorization: Bearer ory_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "a3b2c1d4-e5f6-7890-abcd-ef1234567890",
    "expires_in": "1h"
  }'
Generate a recovery link for an identity. This link can be clicked to automatically recover or activate the account.

​
Query parameters

​
return_to
string
URL to redirect the user to after successful recovery. Must be a pre-configured allowed return URL.

​
Request body

​
identity_id
string
required
UUID of the identity to create a recovery link for.
​
expires_in
string
How long the recovery link remains valid. Accepts duration formats like:
  • 1h (1 hour)
  • 30m (30 minutes)
  • 24h (24 hours)
  • 60s (60 seconds)
If not specified, defaults to the selfservice.methods.code.config.lifespan configuration value.

​
Response

​
recovery_link
string
The complete recovery URL. When visited, this link automatically recovers the account and initiates a settings flow.
​
expires_at
string
Timestamp (RFC3339 format) when the recovery link expires.

​
Example response

{
  "recovery_link": "https://example.com/self-service/recovery?token=abc123def456&flow=xyz789",
  "expires_at": "2026-03-03T15:30:00Z"
}

​
Error responses

  • 400: Invalid request body or duration format
  • 404: Identity not found

​
Usage notes

Recovery links are commonly used for:
  • Email-based account recovery flows
  • “Magic link” authentication
  • Account activation after registration
  • Passwordless onboarding
Use recovery links when:
  • You’re sending recovery via email or another digital channel
  • You want a one-click recovery experience
  • The user’s device can open URLs directly
Use recovery codes when:
  • You need to transmit recovery via SMS or phone
  • You want the user to manually enter a code
  • You need a shorter, more memorizable recovery method
  • The recovery UI is already open on the user’s device

​
Security considerations

  • Recovery links are single-use only
  • Links include sensitive tokens - transmit via secure channels only
  • Set short expiration times for high-security applications
  • Validate that return_to URLs are in your allowlist
  • Never log recovery links in plaintext
  • Consider using recovery codes for SMS/phone delivery

​
Configuration

Configure recovery link behavior in your Kratos configuration: 
selfservice:
  methods:
    link:
      enabled: true
      config:
        lifespan: 1h
        base_url: https://example.com
  allowed_return_urls:
    - https://example.com/dashboard
    - https://example.com/settings

​
Best practices

​
Expiration times

Choose expiration times based on your delivery method:
  • Email recovery: 1-24 hours
  • SMS recovery: 5-15 minutes
  • In-app recovery: 5-30 minutes
  • Admin-initiated: 24-72 hours

​
Delivery methods

Email delivery: 
# Generate link, then send via email service
curl -X POST .../admin/recovery/link \
  -d '{"identity_id": "...", "expires_in": "24h"}'
SMS delivery: 
# Generate code, then send via SMS service
curl -X POST .../admin/recovery/code \
  -d '{"identity_id": "...", "expires_in": "15m"}'

​
Rate limiting

Implement rate limiting to prevent abuse:
  • Limit recovery requests per identity
  • Track failed recovery attempts
  • Consider CAPTCHAs for self-service recovery
  • Monitor for suspicious patterns

​
Audit logging

Log recovery operations for security monitoring:
  • When recovery links/codes are created
  • Which identity they’re for
  • Who created them (admin user/system)
  • Whether they were successfully used
  • Failed recovery attempts

Build docs developers (and LLMs) love

Get started for freeTalk to us