Authio docs

Guides

Set up branded email

Send Authio's sign-in / verify / recovery emails from noreply@yourcompany.com instead of no-reply@authio.com.

Branded email is an Enterprise-plan feature and requires that you've already registered a custom domain for the same root. The from-address must be on the same root domain as the registered custom hostname.

1. Open the custom-domain detail page

In dashboard / Custom domains, click the row for your domain (e.g. auth.yourcompany.com). Scroll to the Branded email card.

2. Enter a from-address

Typical value: noreply@yourcompany.com. The domain part must match the root of your registered custom hostname — auth.yourcompany.com ↔ yourcompany.com is fine; mixing root domains is rejected with from_address_domain_mismatch.

Click Enable branded email. Authio:

  1. Calls SES CreateEmailIdentity for the from-address's domain.
  2. Captures the three DKIM tokens SES generated.
  3. Renders them as <token>._domainkey.yourcompany.com CNAME <token>.dkim.amazonses.com in the dashboard.

3. Publish the three CNAMEs at your DNS provider

Each row in the dashboard has a copy-to-clipboard affordance. Add all three at your DNS provider; they propagate within a few minutes for most providers.

4. Verify

Click Verify DKIM in the dashboard. Authio re-reads the SES identity and updates the status:

  • pending_dkim — DKIM tokens haven't propagated yet. SES is still polling your DNS. Wait a few minutes and click again.
  • pending_ses_verify — DKIM resolved, but SES hasn't marked the identity as “verified for sending” yet. Usually flips within an hour of DKIM success.
  • active — Authio starts routing sign-in email through your identity immediately. The auth-core senderSelector picks up the change inside its 60-second cache TTL.
  • failed — SES marked the DKIM as failed (usually a typo in the CNAMEs). Re-check and click Verify again.

DKIM verification can take 24 hours. SES is conservative; if a CNAME took an hour to propagate it may take SES another hour to retry the lookup. The dashboard's Verify button is safe to re-click as often as needed.

How auth-core decides whether to use it

On every transactional email send (magic-link, email-verify, recovery, etc.), auth-core resolves the per-project sender:

  1. Look up the project's active custom_domains row with branded_email_status = 'active' and a non-null branded_email_from.
  2. If found, set From: <branded_email_from> and route through the authio-ses-branded IAM user (which has Resource: arn:aws:ses:us-east-1:*:identity/*).
  3. Otherwise, send from AUTHIO_EMAIL_FROM via the existing authio-ses-sender path.

The decision is cached for 60 seconds per project; the cache invalidates implicitly on row updates via the TTL backstop. A future /internal/sender/invalidate-project RPC will make the flip near-instantaneous.