Email Webhooks Setup

You need to implement an email webhook on your server. When Mindful Auth calls this webhook, your server should send the appropriate email to the user using the data provided in the webhook payload. The email webhook handles three types of events, differentiated by the event_type field:

verify_email

Sent after a user registers for an account (either via email/password or Magic Login). To activate the new account the user needs to verify their email address.

{
"event_type": "verify_email",
"recordid": 123456789,
"email": "email@example.com",
"name": "John Doe",
"verificationLink": "https://your.domain.com/email-verified/record_id/verificationToken"
}

password_reset

Sent after a user requests a password reset.

{
"event_type": "password_reset",
"recordid": 123456789,
"email": "email@example.com",
"name": "John Doe",
"resetLink": "https://your.domain.com/reset-password/record_id/resetToken"
}

magic_login

Sent after a user requests a magic login link.

{
"event_type": "magic_login",
"recordid": 123456789,
"email": "email@example.com",
"name": "John Doe",
"magicLoginLink": "https://your.domain.com/verify-magic-link/record_id/magicToken"
}

Resending Verification Email

If a user tries to log in but their email is not verified, there are two ways to resend a verification email:

1. End user visits the your.domain.com/resend-verification public page and submits their email address.
2. An admin uses the “Resend Verification Email” admin endpoint API to send end users another verification email. Here is an example cURL request:

curl -X POST https://api.mindfulauth.com/auth/admin/resend-verification-email \
  -H "X-Tenant-Domain: portal.example.com" \
  -H "Authorization: Bearer <internal-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "recordId": "123456789",
    "email": "user@example.com"
  }'

Authentication:

Validates Authorization header (Bearer token) against your internal API key. The X-Tenant-Domain header specifies which hostname’s credentials to use.

Credential Matching Requirements:

• You MUST use the correct X-Tenant-Domain for the recordId being targeted
• The Authorization internal API key MUST match the specified X-Tenant-Domain’s key
• For hostnames with SHARED app IDs (encryption key reuse):
  • portal1.com (app ID “123”) and portal2.com (app ID “123”) have IDENTICAL internal API keys
  • You can use either hostname with their shared key
• For hostnames with DIFFERENT app IDs:
  • portal1.com (app ID “123”) and portal3.com (app ID “456”) have DIFFERENT internal API keys
  • You MUST use the matching X-Tenant-Domain and its corresponding internal API key
  • Using portal1.com’s key with X-Tenant-Domain: portal3.com will fail (403 Unauthorized)

NOTE

• Only resends verification email if account is in “Email Verification Pending” status.
• Includes 5-minute rate limit per email to prevent abuse if internal API key is compromised.

Note

You have the option of manually changing “Authentication Status” from “Email Verification Pending” to “Unlocked” in your database, which will allow the user to log in without verifying their email. However, this is not recommended for security reasons.

Token expirations

All tokens (verificationToken, resetToken, magicToken) have specific expiration times for security purposes:

• Email verification tokens expire in 24 hours.
• Password reset tokens expire in 1 hour.
• Magic login tokens expire in 15 minutes.

If the end user does not use the token within the specified time frame, they will need to request a new email to receive a fresh token.

Security Note

All tokens use a 32-byte base64 encoded string to ensure a high level of security.