Avatar claims and delivery
Sudomimus uses AVATAR for account-avatar consent and AVATAR_ANIMATION for subordinate animation consent. Applications select one avatar source and separately choose whether to receive animation. 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
Section titled “Where avatar appears”| Response | Field | When it appears |
|---|---|---|
Session /userinfo |
picture |
When the static avatar claim resolves to a real or placeholder value. |
Session /userinfo |
picture_animated |
When animation is requested and an avatar is shared. Uses the same identity as picture; falls back to its static URL when account animation is not authorized or available. |
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, animation is requested, and an avatar is shared. Uses the same source and static fallback as Session UserInfo. |
| Token-issuing response envelope | claims.avatar, claims.avatarAnimation |
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
Section titled “Real vs placeholder avatars”The avatar source policy uses the same requirement enum as email and names:
| 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 (avatar = SYNTHETIC_ONLY) and animated avatar sharing is off by default (avatarAnimation = false).
The placeholder avatar is different: it is generated for the (account, sector) pair. 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
Section titled “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.
Set the boolean avatarAnimation preference to receive animation. It must be false when avatar is OFF. Users first authorize their account avatar, then optionally authorize its animation. Declining animation keeps the same account static URL in picture_animated; it never substitutes another virtual identity. Sector virtual animation needs no account-avatar consent. If the selected avatar has no animation, picture_animated also 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
Section titled “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
Section titled “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 account-avatar or subordinate animation consent;
- the developer changes the application’s claim policy;
- the user changes their account avatar;
- the user rotates the sector subject;
- a
SYNTHETIC_FALLBACKclaim 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.
Revoking account-avatar consent removes the account avatar from future UserInfo responses. Revoking only animation consent retains the account static avatar. Both downgrades rotate the relevant sector delivery handles. It cannot recall copies already downloaded by the application or cached outside Sudomimus.
OIDC behavior
Section titled “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
Section titled “Integration checklist”- Request the avatar claim only when your product needs to display a user image.
- Use
SYNTHETIC_ONLYwhen a stable generated avatar is enough and you do not need real profile data. - Use
SYNTHETIC_FALLBACKwhen you prefer the user’s real avatar but need non-blocking login. - Use
REQUIREDonly 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.
Related
Section titled “Related”- Avatar uploads - the account-side upload and processing flow.
- Identity claims and sharing - the policy, grant, and
claimsblock model. - Tokens and verification - how tokens and UserInfo work together.
- Pairwise identity - why sector-scoped identifiers and placeholder identities exist.
- Native claims and the Errand - how native direct-issue handles required claims.