API Documentation

Learn how to integrate the Recovery API into your application.

Quick Start

1. Get an API Key

First, create an API key in your dashboard.

2. Initiate Recovery

When a user requests account recovery, call the initiate endpoint:

POST https://your-recovery-api.netlify.app/api/v1/recovery/initiate
Authorization: Bearer ra_your_api_key_here
Content-Type: application/json

{
  "email": "user@example.com",
  "redirect_url": "https://yourapp.com/recovery/success",
  "webhook_url": "https://yourapp.com/webhooks/recovery" // optional
}

3. Handle Webhook (Optional)

When the user clicks the recovery link, you'll receive a webhook:

POST https://yourapp.com/webhooks/recovery
Content-Type: application/json

{
  "event": "recovery.completed",
  "data": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_email": "user@example.com",
    "recovery_token": "abc123...",
    "timestamp": "2024-01-08T12:00:00Z"
  }
}

API Reference

POST/api/v1/recovery/initiate

Initiate a recovery process for a user.

Headers

Authorization: Bearer {your_api_key}
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
emailstringYesUser's email address
redirect_urlstringYesWhere to redirect after successful recovery
webhook_urlstringNoURL to receive webhook notifications

Response

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_at": "2024-01-08T12:30:00Z",
  "message": "Recovery email sent successfully"
}

Error Responses

401Unauthorized

Invalid or missing API key

400Bad Request

Invalid request body or parameters

429Too Many Requests

Rate limit exceeded (max 5 attempts per email per hour)

Webhooks

When a user clicks their recovery link, we'll send a POST request to your webhook URL.

Webhook Payload

{
  "event": "recovery.completed",
  "data": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_email": "user@example.com", 
    "recovery_token": "abc123...",
    "timestamp": "2024-01-08T12:00:00Z"
  }
}

Best Practices

  • Return a 200 status code to acknowledge receipt
  • Process webhooks idempotently (we may retry failed deliveries)
  • Validate the request_id matches your records
  • Implement your own password reset logic after receiving the webhook

Security

  • ✓Recovery tokens are cryptographically secure and single-use
  • ✓All tokens expire after 30 minutes
  • ✓Rate limiting prevents abuse (5 attempts per email per hour)
  • ✓All API requests require authentication via API key
  • ✓Email addresses are validated and normalized

Need help? Visit your dashboard or check the logs for troubleshooting.