Password Reset

If you forget your password, you can request a reset link via email.

---

Reset Flow

Step 1: Request Reset

Submit your email address to receive a reset link.

Step 2: Check Email

Click the link in the email or use the token with the API.

Step 3: Set New Password

Enter your new password to regain access.

---

Request Password Reset

POST /auth/forgot-password

Initiates a password reset flow.

Request:

{
  "email": "john@example.com"
}

Response (200 OK):

{
  "success": true,
  "message": "If an account with that email exists, a password reset link has been sent."
}

Security

The response always returns success regardless of whether the email exists, for security reasons. This prevents account enumeration attacks.

---

Complete Password Reset

POST /auth/reset-password

Resets the password using the token from the reset email.

Request:

{
  "token": "rst_abc123...",
  "newPassword": "NewSecurePassword456!"
}

Field	Type	Required	Description
token	string	Yes	Reset token from the email link
newPassword	string	Yes	New password (same requirements as signup)

Response (200 OK):

{
  "success": true
}

Response with errors:

{
  "success": false,
  "error": "Invalid or expired reset token"
}

---

Password Requirements

Your new password must meet these requirements:

• Minimum 8 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one number (0-9)

---

Token Expiration

Reset tokens expire after 1 hour. If your token has expired:

1. Request a new reset link
2. Use the new token within 1 hour
3. Complete the password reset

---

Error Responses

Invalid Token

{
  "success": false,
  "error": "Invalid or expired reset token"
}

The token may be:

• Already used (tokens are single-use)
• Expired (older than 1 hour)
• Malformed or tampered with

Password Requirements Not Met

{
  "success": false,
  "error": "Password does not meet requirements"
}

Ensure your new password meets all requirements.

---

C# SDK Example

var client = new ManagementClient(new ManagementClientOptions
{
    ApiBaseUrl = "https://api.terrascale.io"
});

// Request password reset
var forgotResult = await client.Auth.ForgotPasswordAsync(
    new ForgotPasswordRequest(Email: "john@example.com")
);

if (forgotResult.IsSuccess)
{
    Console.WriteLine("Check your email for a reset link!");
}

// Later, when user has the token from email
var resetResult = await client.Auth.ResetPasswordAsync(
    new ResetPasswordRequest(
        Token: "rst_abc123...",
        NewPassword: "NewSecurePassword456!"
    )
);

if (resetResult.IsSuccess)
{
    Console.WriteLine("Password reset successful! You can now log in.");
}
else
{
    Console.WriteLine($"Error: {resetResult.Errors.First().Message}");
}

---

Security Tips

1. Use a unique password - Don’t reuse passwords from other sites
2. Enable MFA - Add extra protection after resetting
3. Check for suspicious activity - Review your account after reset
4. Use a password manager - Store passwords securely

---

Next Steps

• Login - Sign in with your new password
• MFA - Enable two-factor authentication
• Profile - Review your account settings