The Authvio side, meaning the picture claim, its sizes and the change event, is described on docs.authvio.com: Profile pictures. This page covers what a Bolrach platform does with that claim.
The rules
- A member with no picture gets their Authvio photo at sign-in. Members who joined earlier get it from a one-off backfill.
- Your pages and apps show your stored copy. They never load
cdn.authvio.comdirectly. - A picture the member uploads themselves is never replaced by a later Authvio change.
- If they remove their own upload, the Authvio photo comes back, or initials if there is none.
- If they remove the Authvio photo, they get initials, and that choice is remembered.
- Covers start empty, because Authvio has no cover. Members can set or remove a cover at any time.
- Each file has a size limit (a server setting today, with an admin setting coming). There is no limit on how often someone changes their picture.
What you store per member
| Field | Type | Meaning |
|---|---|---|
picture_ref | string | null | Your stored WebP. Null means show initials. |
picture_source | 'authvio' · 'own' · 'none' · null | Where the picture came from. 'none' means the member removed the Authvio photo; null means nothing has been decided yet. |
picture_authvio_url | string | null | The claim you last copied. A new ?v= in the claim means a new Authvio photo. |
cover_ref, cover_source | key · 'own' · 'none' · null | The same pattern for the cover, without the Authvio step. |
In the helper these three fields are one PictureState: { ref: string | null; source: PictureSource; authvioUrl: string | null }, where PictureSource is 'authvio' | 'own' | 'none' | null.
The helper
Import from @empire/storage/authvio-picture (or from the @empire/storage root). It runs on the server only. Apps need nothing from it, because they show the address your API returns.
| Function | When to call it | What it does |
|---|---|---|
decideAuthvioPicture({ claimUrl, current }) | At every Authvio sign-in (web and app) and in the one-off backfill. | Returns { action: 'leave' }, { action: 'seed', url } or { action: 'refresh', url }. Pure, no I/O. |
importAuthvioPicture(ingest, { url, bucket, key, squares?, widths? }) | After a seed or refresh, in the background (never awaited in sign-in). | Copies the Authvio photo into your bucket as WebP and returns { ref, authvioUrl, source: 'authvio', ingest }. Throws on any failure. |
stillApplies(readAtDecision, now) | Before saving a background copy. | True only if ref, source and authvioUrl are unchanged since the decision, so an upload made meanwhile wins. |
removePicture({ current, claimUrl }) | When the member taps Remove on their photo. | Returns { action: 'seed', url } (the picture was not known to be Authvio's, and a claim exists) or { action: 'clear', source }: source is 'none' only when the removed picture was Authvio's, otherwise null. Pure. |
removeAuthvioPictureObjects(links, { bucket, keys, reason, memberPrefix }) | When a picture is replaced or removed, or the account is erased. | Deletes those objects through Storage and returns { deleted, failed, refused }. A failed delete never throws; keys outside memberPrefix (or containing ..) go to refused and are never sent. It throws authvio_picture_member_prefix_required only when memberPrefix is missing, does not end in /, or contains ... |
pictureObjectKeys(stored) | Before deleting a stored picture. | Lists the main key and every size variant of one ingest result. |
authvioPictureUrl(claim) | When you need the claim on its own. | Returns the claim if it is https on cdn.authvio.com, otherwise null. |
How the sign-in decision works
- Source
'own'or'none', or no usable claim:leave. - No stored picture:
seedit from the claim. - Source
'authvio'and the claim differs frompicture_authvio_url:refresh. - In every other case:
leave.
What the copy checks
importAuthvioPicture downloads from cdn.authvio.com over https on your server and nowhere else. A redirect is an error. So is a file over 10 MB (AUTHVIO_PICTURE_MAX_BYTES) or a type outside WebP, JPEG, PNG, GIF, AVIF, HEIC and HEIF; an SVG is always refused. The bytes then go to Storage ingest, the same path a member's own upload takes, and come out as a scanned WebP with EXIF removed. Every copy has a fresh key, so it is cached for a year (AUTHVIO_PICTURE_CACHE_CONTROL). When it throws, the message is one of authvio_picture_url_refused, authvio_picture_fetch_<HTTP status>, authvio_picture_not_image, authvio_picture_too_large, authvio_picture_not_converted or authvio_picture_not_clean; log it and move on. If you pass links, a stored result that is refused (not converted, or not clean) is deleted again before the error is thrown.
Storage access
The API signs in to Storage as its own workload, empire:<app>:storage (audience https://storage.bolrach.com, scope storage:ingest), and storage-api must grant it your bucket. Add storage:delete if it cleans up old pictures, which it should. The service's drop-in carries:
STORAGE_WIF_CLIENT_ID=…
STORAGE_WIF_KEY_FILE=<path to the workload key>
STORAGE_WIF_AUDIENCE=https://storage.bolrach.com
STORAGE_API_URL=<Storage's internal address>Set STORAGE_API_URL to Storage's internal address. The default is the public edge, which refuses server-to-server calls. The Storage owners give you the address, the workload and the grant.
At sign-in
The decision is instant. The copy is not, so start it and let sign-in finish without waiting. When the copy comes back, write it with a compare-and-set update against the row you read (or check stillApplies first). If the member uploaded a photo in the meantime, the write misses and the copy gets deleted. If the copy failed, nothing is written; the next sign-in has another go.
import {
decideAuthvioPicture, importAuthvioPicture, type PictureState,
} from "@empire/storage/authvio-picture";
import { StorageIngest } from "@empire/storage";
import { authvioAuthFromEnv } from "@authvio/workload";
const credential = authvioAuthFromEnv("STORAGE", process.env, {
audience: "https://storage.bolrach.com", scope: "storage:ingest",
});
const ingest = new StorageIngest({ credential, base: process.env.STORAGE_API_URL });
// Member, db, BUCKET, log and dropObjects are your app's own.
// Call this at the end of every Authvio sign-in (web OIDC and the app door).
// It returns at once: sign-in never waits for the copy.
export function afterSignIn(member: Member, claims: { picture?: unknown }) {
const read: PictureState = {
ref: member.picture_ref, source: member.picture_source, authvioUrl: member.picture_authvio_url,
};
const d = decideAuthvioPicture({ claimUrl: claims.picture, current: read });
if (d.action !== "seed" && d.action !== "refresh") return;
const key = `members/${member.id}/${crypto.randomUUID()}.webp`;
void importAuthvioPicture(ingest, { url: d.url, bucket: BUCKET, key, squares: [96, 256, 512] })
.then(async (copy) => {
// Save only if nothing changed since we read the row: an upload made meanwhile wins.
const saved = await db.updatePictureIf(member.id, read, {
ref: copy.ref, source: "authvio", authvioUrl: copy.authvioUrl,
});
if (!saved) await dropObjects(member.id, copy.ingest);
})
.catch((e) => log.warn("Authvio picture not copied; tries again next sign-in", e));
}Remove
Someone who removes a photo they uploaded gets their Authvio photo back. The same applies to any picture not known to be Authvio's (source 'own' or null, for example one written before this helper existed). With no Authvio photo, or when the copy fails, they get initials and source goes back to null, which lets a later Authvio photo fill the gap. Source becomes 'none' in one case only: the picture they removed was the Authvio photo.
import { removePicture, importAuthvioPicture, type PictureSource } from "@empire/storage/authvio-picture";
// db, ingest, BUCKET, newKey, dropOldPicture and Conflict are your app's own.
export async function removePhoto(member: Member, claims: { picture?: unknown }) {
const read = { ref: member.picture_ref, source: member.picture_source, authvioUrl: member.picture_authvio_url };
const d = removePicture({ current: read, claimUrl: claims.picture });
let next = { ref: null as string | null, source: null as PictureSource, authvioUrl: null as string | null };
if (d.action === "seed") {
// The removed picture was not known to be Authvio's: fall back to the Authvio picture.
try {
const copy = await importAuthvioPicture(ingest, { url: d.url, bucket: BUCKET, key: newKey(member.id), squares: [96, 256, 512] });
next = { ref: copy.ref, source: "authvio", authvioUrl: copy.authvioUrl };
} catch {
// The copy failed: initials, not remembered (source null), so the next sign-in tries again.
}
} else if (d.action === "clear") {
next.source = d.source; // 'none' = the Authvio picture was removed; never re-seeded
}
if (!(await db.updatePictureIf(member.id, read, next))) throw new Conflict("Your photo just changed. Look again and try once more.");
await dropOldPicture(member);
}Deleting old objects
An old photo keeps loading from its address until its objects are gone, so delete them on replace, on remove and when the account is erased. Storage checks that the key is inside your grant's bucket and key prefixes, and refuses deletes for a grant with no key prefix. What it cannot know is which member owns a key, so that check is yours. Keep each member's pictures under members/<id>/ (the trailing / stops members/1/ from matching members/10/) and give the helper that folder as memberPrefix. The keys themselves should come from your database, never from the request. With Storage's default name templates the size variants sit beside the main key in the same folder. If you pass your own widthName or squareName, keep the variants in that folder too (no / in the template).
import { removeAuthvioPictureObjects, pictureObjectKeys } from "@empire/storage/authvio-picture";
import { StorageLinks } from "@empire/storage";
// deleteCredential (a workload token with scope storage:delete), storedResult and member are your app's own.
const links = new StorageLinks({ credential: deleteCredential });
const r = await removeAuthvioPictureObjects(links, {
bucket: BUCKET,
keys: pictureObjectKeys(storedResult), // keys YOU recorded for this member, never keys from a request
reason: "profile picture replaced",
memberPrefix: `members/${member.id}/`,
});
if (r.failed.length) log.warn("old picture objects left", r.failed);Bolrach account routes
Bolrach Mail, Workspace and the bolrach.com account use these routes. They are served at https://bolrach.com/api, https://workspace.bolrach.com/api and https://mail.bolrach.com/api, and on bolrach.com the image addresses are same-origin. They are the reference for building the same thing on your platform. They act only on the signed-in member's own row. The web signs in with its session cookie, and apps send the Authvio id_token as Authorization: Bearer.
The member's photo and cover. It answers at once. If their Authvio photo should be copied, that happens in the background, and the next read shows it.
{
"photo": {
"url": "/api/profile-images/9f2c…e1/full-s256.webp",
"urls": {
"96": "/api/profile-images/9f2c…e1/full-s96.webp",
"256": "/api/profile-images/9f2c…e1/full-s256.webp",
"512": "/api/profile-images/9f2c…e1/full-s512.webp"
},
"source": "authvio"
},
"cover": { "url": null, "urls": {}, "source": "none" }
}source is 'own', 'authvio' (your stored copy, never Authvio's address) or 'none' (show initials; url is null).'none' means the member removed their Authvio picture: show initials. 'authvio' with a null url means nothing is stored yet: show the Authvio picture you already have, else initials. Photo sizes are 96, 256 and 512 squares. The cover's url is the 1920 × 640 picture, and its sizes are 640, 1280 and 1920 wide. Loading an image needs no sign-in, because the address holds a random 128-bit id. Images are served as image/webp with nosniff and cached as immutable. A change makes a new id, and any other file name returns 404.
The body is the raw image bytes, with Content-Type set to JPEG, PNG, WebP, HEIC, HEIF, AVIF or a still GIF, and a declared Content-Length. The new picture applies at once, and the previous picture's files are deleted. The response is the new { photo, cover }. Each file has a size limit, and there is no limit per person or per day.
curl -X PUT "https://bolrach.com/api/me/photo" \
-H "Authorization: Bearer $AUTHVIO_ID_TOKEN" \
-H "Content-Type: image/jpeg" \
--data-binary @me.jpgRemoves the photo by the rules above, or sets the cover to 'none'. The response is the new { photo, cover }. If the photo changed between the read and the write, the response is 409 changed.
curl -X DELETE "https://bolrach.com/api/me/photo" \
-H "Authorization: Bearer $AUTHVIO_ID_TOKEN"Photos for up to 200 Authvio subjects at once: { "subjects": [ … ] } returns { "photos": { "<subject>": { url, urls, source } } }. You only get people who share an active organization with the caller, in any product; everyone else is left out. An invalid list returns 400 bad_subjects.
Errors
Every error has the shape { "error": { "code", "message", "status" } }. The message is a sentence you can show the member as it is.
| Status | Code | When |
|---|---|---|
| 400 | empty | No bytes were sent. |
| 401 | unauthenticated | No valid session or token. This is checked before the body is read. |
| 409 | changed | Remove raced another change. Read the profile again. |
| 411 | length_required | No Content-Length, or a chunked body. |
| 413 | too_large | The declared size is over the per-file limit (20 MB by default; an admin setting is coming), so the body is not read. |
| 413 | image_too_large | Storage refused the image's size. |
| 413 | body_not_allowed | A body was sent with GET, DELETE or another method that takes none. |
| 415 | not_an_image | The type is not accepted, or the file is not the image it claims to be. |
| 422 | image_unreadable · image_animated · file_refused | The file is unreadable, animated, or refused by the virus scan. |
| 503 | image_pipeline_unavailable | Storage could not store the picture (unreachable or an unexpected error). Try again shortly. |
In the apps
Flutter apps crop with the shared photo_crop package (pickAndCrop: aspect: 1, round: true for a photo, aspect: 3 for a cover). They upload with the PUT above and show the URLs the API returns. Show the 96 size in lists and the 256 size on the profile. When source is 'none', show initials. Put "Change photo" and "Change cover" on the member's own profile, and "Remove" next to each.