auth.sv - Public Avatars v1

Overview

auth.sv is where a person manages their own SparkVault identity: their verified emails and phones, passkeys, active sessions, the sites they have signed into, and the one photo they choose to publish. It belongs to the person, not to your account.

That published photo is the only part of auth.sv you integrate against, and it is a plain image URL on a second host, my.auth.sv. Point an <img> at it and you are done:

<img src="https://my.auth.sv/ing_019e6f58f7d27c6ebe93cf08b1e6c19b/avatar"
     alt="" width="40" height="40" loading="lazy"
     referrerpolicy="no-referrer"
     style="border-radius:50%;object-fit:cover">

The Hosts

The Avatar URL

The path is case-sensitive and the hex must be lowercase. Query strings are ignored, not honored: there is no ?s= size parameter and no ?d= default-image parameter.

Which Selector Do You Have?

Hashing an Email or Phone

The hash is a plain lowercase-hex SHA-256 of the normalized identifier. No salt, no prefix, no type tag. Normalize exactly as described — SparkVault applies the same two rules and nothing more:

• Email — trim surrounding whitespace, then lowercase. "  Ada@Example.COM " becomes ada@example.com.
• Phone — E.164 including the leading +, with whitespace removed. "+1 415 555 0123" becomes +14155550123.

Test Vectors

Check your implementation against these before you wire it to real data. If your digest does not match, your normalization is wrong — and a wrong hash fails silently, returning a perfectly valid placeholder rather than an error.

ada@example.com
  b5fc85e55755f9e0d030a10ab4429b6b2944855f9a0d60077fe832becbc41d72

+14155550123
  36a2cef4ff9bf7a1abd2a93359136b870393be4106e6c5d19b72ff564f9deca4

async function avatarUrl(email) {
  const normalized = email.trim().toLowerCase();
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(normalized));
  const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
  return `https://my.auth.sv/${hex}/avatar`;
}

import { createHash } from 'node:crypto';

export function avatarUrl(email) {
  const hex = createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
  return `https://my.auth.sv/${hex}/avatar`;
}

// Phone: E.164 with whitespace removed, the leading + kept.
export function avatarUrlForPhone(phone) {
  const hex = createHash('sha256').update(phone.replace(/\s+/g, '')).digest('hex');
  return `https://my.auth.sv/${hex}/avatar`;
}

import hashlib


def avatar_url(email: str) -> str:
    normalized = email.strip().lower()
    digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
    return f"https://my.auth.sv/{digest}/avatar"

require "digest"

def avatar_url(email)
  digest = Digest::SHA256.hexdigest(email.strip.downcase)
  "https://my.auth.sv/#{digest}/avatar"
end

function avatar_url(string $email): string
{
    // mb_strtolower, not strtolower: strtolower is ASCII-only and leaves a
    // non-ASCII capital untouched, which hashes to a different digest.
    $digest = hash('sha256', mb_strtolower(trim($email), 'UTF-8'));
    return "https://my.auth.sv/{$digest}/avatar";
}

import (
	"crypto/sha256"
	"encoding/hex"
	"strings"
)

func AvatarURL(email string) string {
	sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(email))))
	return "https://my.auth.sv/" + hex.EncodeToString(sum[:]) + "/avatar"
}

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Locale;

static String avatarUrl(String email) throws Exception {
    // Locale.ROOT matters: the Turkish locale lowercases "I" to a dotless i.
    String normalized = email.strip().toLowerCase(Locale.ROOT);
    byte[] digest = MessageDigest.getInstance("SHA-256")
        .digest(normalized.getBytes(StandardCharsets.UTF_8));
    return "https://my.auth.sv/" + HexFormat.of().formatHex(digest) + "/avatar";
}

using System.Security.Cryptography;
using System.Text;

static string AvatarUrl(string email)
{
    var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(email.Trim().ToLowerInvariant()));
    // Convert.ToHexString returns UPPERCASE; the URL requires lowercase.
    return $"https://my.auth.sv/{Convert.ToHexString(bytes).ToLowerInvariant()}/avatar";
}

# Normalize first (trim + lowercase), then hash. Use sha256sum on Linux.
hex=$(printf '%s' 'ada@example.com' | shasum -a 256 | cut -d' ' -f1)
echo "https://my.auth.sv/$hex/avatar"

Embedding

This is an image URL and nothing else. There is no redirect to follow, no API call to make, no token to attach, no CORS preflight to satisfy, and no onerror fallback to write — the URL always renders. Hotlinking is the intended usage: serve it straight from my.auth.sv.

<!-- Beside the person's name: the image is decorative, so alt is empty. -->
<span class="user">
  <img src="https://my.auth.sv/ing_019e6f58f7d27c6ebe93cf08b1e6c19b/avatar"
       alt="" width="40" height="40" loading="lazy"
       referrerpolicy="no-referrer"
       style="border-radius:50%;object-fit:cover">
  Ada Lovelace
</span>

<!-- Standing alone: name the person in alt. -->
<img src="https://my.auth.sv/b5fc85e55755f9e0d030a10ab4429b6b2944855f9a0d60077fe832becbc41d72/avatar"
     alt="Ada Lovelace" width="96" height="96" loading="lazy"
     referrerpolicy="no-referrer">

export function Avatar({ selector, name, size = 40 }) {
  return (
    <img
      src={`https://my.auth.sv/${selector}/avatar`}
      alt={name ? `${name}'s avatar` : ''}
      width={size}
      height={size}
      loading="lazy"
      decoding="async"
      referrerPolicy="no-referrer"
      style={{ borderRadius: '50%', objectFit: 'cover' }}
    />
  );
}

import Image from 'next/image';

// `unoptimized` is required: without it next/image proxies every avatar
// through your server, which breaks revocation and concentrates every
// fetch on one IP. See "Common Mistakes" below.
export function Avatar({ selector, name, size = 40 }) {
  return (
    <Image
      src={`https://my.auth.sv/${selector}/avatar`}
      alt={name ? `${name}'s avatar` : ''}
      width={size}
      height={size}
      unoptimized
      referrerPolicy="no-referrer"
      style={{ borderRadius: '50%', objectFit: 'cover' }}
    />
  );
}

<script setup>
const props = defineProps({ selector: String, name: String, size: { type: Number, default: 40 } });
</script>

<template>
  <img
    :src="`https://my.auth.sv/${props.selector}/avatar`"
    :alt="props.name ? `${props.name}'s avatar` : ''"
    :width="props.size"
    :height="props.size"
    loading="lazy"
    referrerpolicy="no-referrer"
    style="border-radius:50%;object-fit:cover"
  />
</template>

Sizing

There are no URL sizing parameters. Set width and height (which also reserves layout space and avoids a shift) and let CSS do the rest. Images are always square, so border-radius:50% gives you a circle with no cropping surprises.

Content Security Policy

If your pages set a CSP, allow the host in img-src. Nothing else is needed — no connect-src entry, because nothing is ever fetched:

Content-Security-Policy: img-src 'self' data: https://my.auth.sv

Referrer

referrerpolicy="no-referrer" is recommended on every avatar embed. Without it the browser sends the URL of the page doing the embedding to my.auth.sv on each load. Nothing depends on that header, so suppressing it costs you nothing.

Common Mistakes

Each of these is code an integration writes by default, and each one breaks something:

The picture Claim

If you sign people in with SparkVault Identity, you never need to build an avatar URL: the token already carries one. The picture claim is the standard OIDC name (OIDC Core 1.0 §5.1), so libraries that map picture to a profile image work with no custom wiring.

// Verify the signature before trusting a claim: an unverified decode reads the
// payload as given, so `picture` would be whatever the token's holder wrote.
const claims = await verifyIdToken(idToken);

if (claims.picture) {
  // Set as a property, never interpolated into markup.
  const img = document.createElement('img');
  img.src = claims.picture;
  img.alt = '';
  img.width = img.height = 40;
  img.loading = 'lazy';
  img.referrerPolicy = 'no-referrer';
  img.style.borderRadius = '50%';
  slot.replaceChildren(img);
} else {
  slot.replaceChildren(renderInitials(claims.identity));  // your own placeholder, as a node
}

import { createHash } from 'node:crypto';

const avatarUrl = (email) =>
  `https://my.auth.sv/${createHash('sha256').update(email.trim().toLowerCase()).digest('hex')}/avatar`;

const rows = contacts.map((c) => `
  <li>
    <img src="${avatarUrl(c.email)}" alt="" width="32" height="32"
         loading="lazy" referrerpolicy="no-referrer" style="border-radius:50%">
    ${escapeHtml(c.name)}
  </li>
`).join('');

Response Contract

Status Codes

What You Get Back

Caching and Revocation

Please honor the cache headers. Revocation works by the object ceasing to exist: a withdrawn photo stops being served at the bucket immediately and clears everywhere, edge caches included, within the stored copy's 300-second TTL, after which the URL serves the placeholder. There is no purge path. If you mirror the bytes onto your own storage, or cache them indefinitely, you will keep publishing a photo the person has already withdrawn.

Publication runs the same clock in reverse. The placeholder is cacheable for 60 seconds at the URL a photo will occupy, so a newly published avatar can take up to a minute to appear at a URL that was requested moments earlier. Neither the placeholder nor a 404 is ever stored in the edge cache, which is what keeps that window short.

Embedded images are fetched by your visitors' browsers, so ordinary usage never approaches the edge rate limit on this host. Bulk-fetching many avatars from a single server address will trip it.

Privacy and Consent

The photo belongs to the person, and they hold two switches in their auth.sv portal. Both are on by default, and either one can go off at any moment with no notice to you:

Treat the URL as a live pointer, never as a fact you have learned. Do not persist the image, and do not persist a derived "this person has an avatar" flag — both go stale the moment the person changes their mind, and the URL is stable enough that you never need to.

Verify Your Integration

One request tells you which of the three responses you are getting, without opening a browser:

curl -sI https://my.auth.sv/ing_019e6f58f7d27c6ebe93cf08b1e6c19b/avatar \
  | grep -iE '^HTTP/|^content-type:|^cache-control:|^x-sv-avatar:'

# HTTP/2 200
# content-type: image/jpeg
# cache-control: public, max-age=300
# x-sv-avatar: stored

The auth.sv Portal

auth.sv is the person's own account page, not yours. Anyone who has verified with SparkVault Identity can sign in there and manage:

• Verified emails and phone numbers, and the per-identifier avatar lookup toggles
• The public avatar itself: upload, replace, remove, and the master visibility switch
• Passkeys, two-factor authentication, and backup identifiers
• Active sessions, with the ability to end them individually or everywhere
• Connected sites: which applications they have signed into, and revoking that access

You do not proxy or wrap the portal. To send someone to their photo, link https://auth.sv/public directly. The SDK's portalUrl() builds deep links to the other screens — home, identity, security, sessions, and sites — and has no public section, so asking it for one throws. See JavaScript SDK.