User Addresses & Email Verification Lifecycle

Accurate legal addresses and verified email identities are essential for domain registration compliance (ICANN / DENIC WHOIS requirements on ternisdomains.de), tax compliance (reverse-charge VAT in Germany and the EU), and security verification.

1. User Address Architecture #

Ternis Auth supports multiple user addresses with primary and billing classifications:

Database Structure (user_addresses) #

• type: billing, shipping, legal, office, home
• street and optional street_line_2
• postal_code and city
• state / province
• country_code: 2-letter ISO 3166-1 alpha-2 code (e.g. DE, AT, CH, US)
• is_primary: Flag indicating the primary default address
• is_billing: Flag indicating the active billing invoice address

1.1. OpenID Connect Address Claim Specification #

When an application requests the address scope during OAuth authorization, the /oauth/userinfo response returns the address formatted according to the OpenID Connect Core 1.0 Address Claim Specification:

{
  "sub": "b2f6b897-4001-460d-8386-db93f1d8c1c4",
  "address": {
    "formatted": "Friedrichstraße 44, Aufgang B, 3. OG, 10117 Berlin, Berlin, DE",
    "street_address": "Friedrichstraße 44\nAufgang B, 3. OG",
    "locality": "Berlin",
    "region": "Berlin",
    "postal_code": "10117",
    "country": "DE"
  }
}

2. Multi-Email & Email Verification Lifecycle #

Users often possess multiple email addresses (e.g. corporate email, personal Gmail, domain notification alias).

Ternis Auth decouples the primary login identifier from secondary notification emails:

[ User Account: Elena Rostova ]
    |
    +---> member@ternis.org       (Primary  - Verified)
    +---> elena@personal.org      (Alias    - Verified)
    +---> elena.backup@gmail.com  (Backup   - Unverified)

Verification Flow: #

1. Adding an Email: Calling POST /api/v1/user/emails or using /account creates a UserEmail record and generates a 48-character cryptographic token (verification_token).
2. Verification Link: The user receives a link:

   https://auth.ternis.net/email/verify/{token}
   

3. Activation: Visiting the URL or calling POST /api/v1/user/emails/{id}/verify sets verified_at = now() and nullifies the token.
4. Primary Email Synchronization: When the primary email is verified, users.email_verified_at is atomically updated, ensuring that standard OIDC email_verified: true claims remain consistent across all connected applications.