Avatar API
Register avatars, authenticate sessions, retrieve and update profiles, manage email verification, and handle password reset flows.
All endpoints are relative to https://api.oasisomniverse.one/api (production) or http://localhost:4000/api (local ONODE).
Response Envelope
Every OASIS API response wraps its payload in a standard envelope:
{
"result": "…", // the returned payload (object, array, or null)
"isError": false, // true when a hard error occurred
"isWarning": false, // true for soft warnings (non-fatal)
"message": "Success", // human-readable status or error message
"detailedMessage": "" // extended diagnostic detail (may be empty)
}
Always check isError first. A 200 OK HTTP status does not guarantee success — OASIS returns isError: true inside the envelope for business-logic failures (e.g. username already taken).
Register
Creates a new avatar. Sends a verification email to the supplied address.
Request body
| Field | Type | Description |
|---|---|---|
usernamerequired | string | Unique username (3–32 chars, alphanumeric + underscores) |
emailrequired | string | Unique email address — used for login and verification |
passwordrequired | string | Min 8 characters |
title | string | Display name / avatar title |
providerType | string | Storage provider override (default: configured ONODE default) |
const res = await fetch('/api/avatar/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'david', email: 'david@example.com', password: 's3cur3pass!', title: 'David' }) }); const { result, isError, message } = await res.json(); if (isError) throw new Error(message);
Authenticate
Authenticates an avatar by username/email + password. Returns a JWT token valid for 7 days.
Request body
| Field | Type | Description |
|---|---|---|
username | string | Username or email (one required) |
email | string | Email or username (one required) |
passwordrequired | string | Account password |
Response result
| Field | Type | Description |
|---|---|---|
jwtToken | string | Bearer token — include in Authorization header for all authenticated requests |
id | guid | Avatar unique identifier |
username | string | Canonical username |
email | string | Verified email address |
karmaTotal | number | Total karma score at login time |
Avatars with unverified email addresses will receive isError: true on authenticate until the verification link is clicked.
Get Avatar
Returns the full avatar profile for the given ID. Requires a valid JWT in the Authorization: Bearer <token> header.
Get All Avatars
Returns all avatars. Admin-only — requires an avatar with AvatarType: Admin.
Update Avatar
Updates avatar fields. Only the authenticated avatar owner or an Admin may update a profile.
Updatable fields
| Field | Type | Notes |
|---|---|---|
title | string | Display name |
description | string | Bio / about text |
username | string | Uniqueness enforced — returns isError on conflict |
email | string | Triggers re-verification email |
image | string | URL or base64 avatar image |
dob | string (ISO 8601) | Date of birth |
Delete Avatar
Soft-deletes the avatar. The record is retained in storage but marked inactive. Admin-only.
Email Verification
Called automatically when the user clicks the link in their verification email. Query param: token.
Re-sends the verification email. Rate-limited to 3 per hour per email address.
Password Reset
Sends a password-reset email. Body: { "email": "…" }.
Resets the password using the token from the email. Body: { "token": "…", "password": "…", "confirmPassword": "…" }.