Skip to main content
One idea at a time

Verification proves control of an email address

Someone registers using Sam's email address. The email looks valid, but the server does not yet know whether that person can receive messages at the address.

Email verification asks the person to return a secret delivered to that inbox. A successful return demonstrates access to the address at that moment.

It does not prove a legal identity, continued future control, or membership in a workspace. Those are different facts.

The token has one purpose​

Taskboard creates a random token, stores its hash with a verification purpose and expiry, and records an email job. The email includes the raw token needed for verification. That means the job payload contains the secret link even though the token table stores a hash. Production access controls and payload retention must account for that copy.

The token record also points to the user. A verification request must check the hash, intended purpose, expiry, and consumed state. A reset-password token must not be accepted merely because it has a matching token format.

raw token from email
  -> hash for lookup
  -> check purpose and expiry
  -> mark token consumed and email verified

This is a conceptual flow. The transaction and checks live in the authentication module.

Consumption needs atomicity​

Two requests can submit the same verification link. Checking consumedAt and then changing it in unrelated statements permits a race.

The operation needs a conditional update or equivalent transaction coordination so only an unconsumed, unexpired token can make the change. Updating the account's verified state belongs in that same transaction.

Email scanners sometimes open links automatically. A production user interface should distinguish viewing a verification page from submitting the action to the API. A GET request that consumes the token can surprise people before they interact.

The reference API exposes verification as a POST operation. The frontend route that presents the email link is a separate concern from the backend's token consumption.

Delivery is another system​

A committed token can exist while its email remains queued or retrying. The worker delivers it through SMTP. The application needs a supportable way to explain delayed delivery without returning the secret in normal API responses.

Development email preview is intentionally different from production delivery. A local preview demonstrates the message content and delivery path. It does not establish that a real provider will avoid spam filtering.

Does email verification give Sam access to Acme?

No. It verifies Sam's email address. Acme access still requires a membership established through the workspace's authorized flow.

Verification records one narrow fact. Purpose, expiry, and atomic consumption keep that fact tied to the intended operation.

Read api/src/auth.ts Read api/src/jobs.ts