---
title: User Addresses & Email Verification Lifecycle
category: User Identity & Compliance
order: 11
badge: Compliance & Identity
description: Architecture specification for multi-address management, OpenID Connect Core 1.0 address claims, and email verification lifecycles.
---

# 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](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim):

```json
{
  "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.