Profile Picture & Avatar CDN Engine

Ternis Auth includes a high-performance Avatar and Media CDN Engine designed to serve user profile images, crisp SVG vector initials, and graceful fallback silhouettes at ultra-low latency.

Media delivery is decoupled from primary authentication logic and served across dedicated cookieless CDN domains: user.t-cdn.de and avatar.t-cdn.de.

1. Dedicated CDN Domains #

2. Direct Avatar URL Patterns #

Client applications can display avatars directly in HTML without making authenticated API calls or parsing JSON:

https://user.t-cdn.de/{user_id}.png
https://avatar.t-cdn.de/{username}.png
https://avatar.t-cdn.de/{username}.svg

URL Resolution Matrix #

3. Query Customization Parameters #

You can customize size, styling, and fallback behavior via URL query strings:

GET https://avatar.t-cdn.de/elena.rostova.png?size=512&bg=4F46E5&color=FFFFFF

4. The Graceful Fallback Guarantee (Never Broken Images) #

A common issue with web applications is broken image icons (❌) when an avatar cannot be found.

Ternis Auth solves this with a strict HTTP 200 Fallback Contract:

1. When an unknown user ID or uninitialized avatar is requested, the endpoint returns HTTP 200 OK with a clean silhouette or generated initials.
2. The response includes diagnostic headers:

   HTTP/1.1 200 OK
   Content-Type: image/png
   X-Ternis-User-Found: 0
   X-Ternis-Fallback: default-avatar
   

3. Your frontend <img> tags will always render smoothly.

[!NOTE] If your backend needs to programmatically check whether a custom avatar exists, pass ?fallback=404. The server will return HTTP 404 Not Found if no custom avatar has been uploaded.

5. HTML & Frontend Implementation #

Standard User Profile Image #

<img 
  src="https://user.t-cdn.de/b2f6b897-4001-460d-8386-db93f1d8c1c4.png?size=128" 
  alt="User Avatar"
  width="64"
  height="64"
  class="rounded-full border border-slate-200"
  loading="lazy"
/>

High-DPI Vector Initials #

<img 
  src="https://avatar.t-cdn.de/elena.rostova.svg" 
  alt="Elena Rostova"
  width="48"
  height="48"
/>

6. Performance, Caching & CDNs #

1. HTTP Caching: Avatar responses include robust cache headers: Cache-Control: public, max-age=86400, stale-while-revalidate=604800, immutable
2. Conditional GET: Responses include an ETag. Subsequent browser requests containing If-None-Match receive an instant 304 Not Modified without data transfer.
3. CORS Headers: All avatar endpoints send Access-Control-Allow-Origin: *, allowing client applications to load avatars onto HTML5 <canvas> elements for client-side cropping or image processing without CORS violations.

7. Changing & Managing Profile Pictures #

Users can manage their profile pictures both via the self-service web interface and programmatically via API.

Via Web Account Dashboard #

Navigate to /account in the browser:

• Upload Image: Choose any PNG, JPG, JPEG, WebP, SVG, or GIF file up to 5MB. The backend automatically performs centered square-cropping and high-quality compression.
• External Image URL: Alternatively, link an external image URL (e.g. your hosted CDN, Gravatar, or GitHub avatar).
• Reset to Default: One-click reset cleanly purges the stored image file and reverts back to the platform's auto-generated deterministic initials.

Programmatic API #

Upload or Update Avatar

# File upload
curl -X POST "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>" \
  -F "avatar=@/path/to/my-photo.png"

# Or link external URL
curl -X POST "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"avatar_url": "https://cdn.example.com/avatars/me.jpg"}'

Reset Avatar to Default

curl -X DELETE "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>"