POST /v1/users/me/avatar
Upload an avatar image. Multipart/form-data.
::: tip Auth Required: cookie or Bearer. :::
Request
POST /v1/users/me/avatar
| Header | Required | Notes |
|---|---|---|
Cookie: identsphere_at=... OR Authorization: Bearer ... | yes | — |
Content-Type: multipart/form-data | yes | Standard multipart upload. |
Form fields
| Field name | Type | Required | Notes |
|---|---|---|---|
avatar (preferred) OR file | file | yes | The image bytes. |
Accepted content types: image/jpeg, image/png, image/gif, image/webp.
Max size: 5 MiB.
Response
200 OK
{ "avatar_url": "https://files.example.com/avatars/1c8b2a5e-.../abc.png" }
The URL is persisted on users.avatar_url. The prior avatar (if any) is
deleted from object storage asynchronously.
Error responses
| Status | Code | When |
|---|---|---|
| 400 | invalid_input | Missing field, wrong content type, file > 5 MiB. |
| 401 | authentication_required | No valid auth credential. |
| 404 | not_found | User no longer exists. |
| 413 | (raw) | Request body exceeded the 5 MiB limit — rejected by the body-limit layer before the multipart parser runs. |
| 500 | internal_error | Storage write failure. |
Example: curl
curl -X POST https://auth.example.com/v1/users/me/avatar \
-b cookies.txt \
-F "avatar=@./me.png"
Notes
- The storage backend is whatever the host configured: local FS, S3, R2, GCS, MinIO.
- Avatar paths follow
avatars/{user_id}/{uuid}.{ext}. - Old avatars are best-effort deleted; failures are logged, not returned.