Email Verification

AutoCom requires email verification for new accounts and email address changes to ensure users own their email addresses.

Overview

Email verification is triggered in two scenarios:

1. New user registration - Via tenant registration or invitation acceptance
2. Email address change - When a user updates their email via profile settings

Verification Flow

1. Trigger Verification

When an email needs verification, the system sends an email with a verification link:

https://app.autocom.example.com/email/verify/123/abc123hash?tenant=tenant-id

The link includes:

• User ID
• Verification hash (SHA1 of email)
• Tenant context (if applicable)

2. Verify Email

The verification endpoint validates the hash and marks the email as verified.

GET /api/v1/email/verify/{id}/{hash}?tenant=tenant-id

Success response:

{
  "message": "Email verified successfully."
}

Already verified response:

{
  "message": "Email is already verified.",
  "already_verified": true
}

Error response (invalid hash):

{
  "message": "The given data was invalid.",
  "errors": {
    "hash": ["Invalid verification link."]
  }
}

API Endpoints

Resend Verification Email

Request a new verification email for the authenticated user.

POST /api/v1/profile/email/resend-verification
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
X-Tenant: your-tenant-id

Success response:

{
  "message": "Verification email sent."
}

Already verified response:

{
  "message": "Email is already verified."
}

Check Verification Status

The verification status is included in the profile response:

GET /api/v1/profile
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
X-Tenant: your-tenant-id

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "user@example.com",
  "email_verified": true,
  ...
}

Email Change Verification

When a user changes their email address, the new email must be verified:

PUT /api/v1/profile/email
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
X-Tenant: your-tenant-id
Content-Type: application/json

{
  "email": "newemail@example.com",
  "password": "current_password"
}

Response:

{
  "message": "Email updated. Please verify your new email address.",
  "email": "newemail@example.com",
  "requires_verification": true
}

Important: The current password is required to change email addresses as a security measure.

Email Template

The verification email includes:

• Organization name
• Verification link
• Expiration notice
• Security warning about unexpected emails

Frontend Integration

Verification Page

// Parse verification link parameters
const params = new URLSearchParams(window.location.search);
const tenantId = params.get('tenant');

// Verify email on page load
async function verifyEmail(userId: string, hash: string, tenantId?: string) {
  const url = `/api/v1/email/verify/${userId}/${hash}${tenantId ? `?tenant=${tenantId}` : ''}`;

  const response = await fetch(url, {
    method: 'GET',
  });

  if (response.ok) {
    // Show success message and redirect to login
    window.location.href = '/login';
  }

  return response.json();
}

Resend Verification

async function resendVerification(accessToken: string, tenantId: string) {
  const response = await fetch('/api/v1/profile/email/resend-verification', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant': tenantId,
    },
  });

  return response.json();
}

Activity Logging

Email verification events are logged:

Action	Description
email_changed	User updated their email address
email_verified	Email was successfully verified

Checking Verification Status

You can check if a user's email is verified in multiple ways:

Via Auth/Me Endpoint

GET /api/v1/auth/me
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
X-Tenant: your-tenant-id

Via Profile Endpoint

GET /api/v1/profile
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
X-Tenant: your-tenant-id

Both return an email_verified boolean field.