Avatar claims and delivery

View as Markdown

Sudomimus has two avatar identity claims, STATIC_AVATAR and ANIMATED_AVATAR, alongside email, first name, and last name. The general policy and consent model is covered in Identity claims and sharing; this page focuses on the avatar-specific delivery contract.

When an avatar claim is emitted, UserInfo returns picture for the static avatar and picture_animated for the animated avatar. Sudomimus scopes those URLs to the account and the application’s sector.

Where avatar appears

Surface	Field	When it appears
Session `/userinfo`	`picture`	When the static avatar claim resolves to a real or placeholder value.
Session `/userinfo`	`picture_animated`	When the animated avatar claim resolves to a real or placeholder value. Falls back to `picture` when the selected avatar has no animation.
OIDC `/userinfo`	`picture`	When `profile` scope is granted and the static avatar claim resolves to a real or placeholder value.
OIDC `/userinfo`	`picture_animated`	When `profile` scope is granted and the animated avatar claim resolves to a real or placeholder value. Falls back to `picture` when the selected avatar has no animation.
Token-issuing response envelope	`claims.staticAvatar`, `claims.animatedAvatar`	Always included in the `claims` block so the client can see the application’s policy and the user’s grant state.

The URL is safe to use as an image source. Do not parse it, infer identity from it, or treat it as a stable user identifier. Your user key is payload sub on an application access token, or standard sub on an OIDC ID token.

Real vs placeholder avatars

Both avatar claims follow the same claim policy enum as the other identity claims:

Policy	Avatar behavior
`OFF`	No matching avatar field is emitted.
`OPTIONAL`	Emits the user’s account avatar only after the user grants the avatar claim. Otherwise it is omitted.
`REQUIRED`	Emits the user’s account avatar after the user grants the avatar claim. Non-interactive issue points reject instead of minting a token without it.
`SYNTHETIC_ONLY`	Always emits the sector placeholder avatar. It never asks for or shares the user’s account avatar.
`SYNTHETIC_FALLBACK`	Emits the user’s account avatar when granted; otherwise emits the sector placeholder avatar. It never blocks login.

The user’s account avatar is the real avatar claim value. It may be an uploaded image or Sudomimus’s generated account avatar fallback, but it is still the account-level avatar the user controls. Applications default to a static placeholder avatar (staticAvatar = SYNTHETIC_ONLY) and animated avatar sharing is off by default (animatedAvatar = OFF).

The placeholder avatar is different: it is generated for the (account, sector) pair and stored with the sector subject’s placeholder identity. Two applications in the same sector can therefore see the same placeholder avatar for a user; applications in different sectors receive unrelated placeholder identities.

Static and animated projections

Account avatars have a static URL and an animated URL. The static projection is the safest default for normal profile UI. The animated projection is for products that intentionally support motion, such as richer profile cards or game/social surfaces.

If the selected avatar has no animation, the private picture_animated claim falls back to the static projection. That means clients can render the animated field when they support animation without first checking whether the source was animated.

Sector-scoped delivery URLs

Even when the claim resolves to the user’s account avatar, the value the application sees is a sector-scoped delivery URL. That matters for privacy:

Treat the URL as opaque; do not parse identifiers out of it.
Different sectors see different delivery URLs for the same account avatar.
If the user rotates their sector subject, Sudomimus also regenerates the placeholder identity and avatar delivery handles for that sector.
If a previously granted avatar claim stops being granted, Sudomimus rotates the real-avatar delivery handle for that account and sector.

Applications should store the user’s current avatar URLs only as display profile data. Do not use them for login, account merge, fraud checks, allow-lists, or cross-application correlation.

Updates, revocation, and caching

Claim grants are read live by UserInfo. The next /userinfo response may add, remove, or change the avatar field when:

the user grants or revokes either avatar claim;
the developer changes the application’s claim policy;
the user changes their account avatar;
the user rotates the sector subject;
a SYNTHETIC_FALLBACK claim switches between real and placeholder because the grant changed.

Treat picture and picture_animated as replaceable profile fields. When you receive a new value, update your stored display avatar. When a field is absent, keep your own default avatar or clear the previously imported one according to your product rules.

Revocation prevents future token issues from sharing the real avatar and rotates Sudomimus’s sector delivery handle. It cannot recall copies already downloaded by the application or cached outside Sudomimus.

OIDC behavior

OIDC /userinfo maps avatar claims to picture and the private picture_animated claim. Both fields are controlled by the avatar claim outcome and the profile scope:

{
  "sub": "<sector subject>",
  "picture": "<sector-scoped static avatar URL>",
  "picture_animated": "<sector-scoped animated avatar URL>"
}

If profile was not granted, both OIDC avatar fields are absent even when the claim policy would otherwise emit an avatar, and no avatar delivery is materialized for that token issuance. If the policy emits a placeholder avatar, the OIDC values follow the same sector-scoped placeholder delivery contract.

Integration checklist

Request the avatar claim only when your product needs to display a user image.
Use SYNTHETIC_ONLY when a stable generated avatar is enough and you do not need real profile data.
Use SYNTHETIC_FALLBACK when you prefer the user’s real avatar but need non-blocking login.
Use REQUIRED only when a real account avatar is product-critical and your client can handle claim-gate recovery.
Use the static field for ordinary profile UI; use the animated field only on surfaces that intentionally support motion.
Key users by subject / sub, never by avatar URLs.
Handle the avatar field being missing or changing between UserInfo requests.

Avatar uploads - the account-side upload and processing flow.
Identity claims and sharing - the policy, grant, and claims block model.
Tokens and verification - where avatar URL fields live in JWTs.
Pairwise identity - why sector-scoped identifiers and placeholder identities exist.
Native claims and the Errand - how native direct-issue handles required claims.