OASIS Learn/Module 2
Beginner ⏱ 25 min

Avatar & Identity — SSO Across Every Platform

The Avatar is the cornerstone of OASIS. One identity, one wallet, one karma score — carried seamlessly across every game, app and metaverse built on the platform.

What you'll learn

  • How OASIS Avatar SSO works and why it matters
  • Register, authenticate, update and delete avatars via the SDK
  • Read and write the avatar's inventory
  • Manage multiple concurrent sessions
  • Look up avatars by email, username or ID

How Avatar SSO Works

When a user logs into any OASIS-connected app, they receive a JWT token tied to their Avatar ID. That same JWT is valid across every OASIS API — WEB4 through WEB10 — and every OApp that trusts the OASIS identity layer. There's no OAuth dance between your apps; the token is issued once and accepted everywhere.

🌍
Real-world use case — cross-game identity

A player earns a rare sword NFT in Our World (the flagship OASIS game). When they log into your indie game built on OASIS, their wallet — and that sword — are already there. Your game queries oasis.avatar.getAvatarInventory() and renders it without any special integration with Our World. That's the power of shared identity.

Registering an Avatar

Call oasis.auth.register(). If you need raw control (e.g. setting provider-specific fields), use oasis.avatar.register() directly — but for most apps the auth helper is the right choice.

register-avatar.js
import { oasis } from './oasis.js';

const result = await oasis.auth.register({
  title:           'Dr',              // Mr, Mrs, Ms, Dr, Prof, Rev, Mx…
  firstName:       'Ada',
  lastName:        'Lovelace',
  email:           'ada@example.com',
  password:        'SecurePassw0rd!',
  confirmPassword: 'SecurePassw0rd!',
  username:        'ada_lovelace',
  avatarType:      'User',           // 'User' | 'Wizard' | 'God'
  acceptTerms:     true
});

console.log(result.session.avatarId);   // GUID — store this!

Avatar types

TypeDescription
UserStandard end-user account. Start here for all player/user registrations.
WizardDeveloper/builder account with elevated OApp publishing permissions.
GodPlatform administrator. Do not create programmatically.

Looking Up Avatars

You can fetch any avatar by ID, email or username. ID lookups are fastest; prefer them in hot paths.

javascript
// By ID (fastest)
const { result: avatar } = await oasis.avatar.getAvatarDetail({ id: avatarId });

// By email
const { result: byEmail } = await oasis.avatar.getAvatarDetailByEmail({ email: 'ada@example.com' });

// By username
const { result: byUsername } = await oasis.avatar.getAvatarDetailByUsername({ username: 'ada_lovelace' });

// List all avatars (admin only)
const { result: all } = await oasis.avatar.getAll();

// Get avatar names for a leaderboard (lightweight)
const { result: names } = await oasis.avatar.getAllAvatarNames({
  includeUsernames: true,
  includeIds: true
});

The Avatar object

FieldTypeDescription
idGUIDUnique avatar identifier
usernamestringDisplay name
emailstringLogin email
firstName / lastNamestringReal name
karmanumberCurrent total karma score
levelnumberAvatar level (derived from XP)
xpnumberExperience points
avatarTypeenumUser / Wizard / God
createdDateISO dateAccount creation timestamp
jwtTokenstringCurrent session token (auth responses only)

Updating an Avatar

Use oasis.avatar.update() to change profile fields. You must be authenticated as the avatar you're updating, or hold admin credentials.

javascript
const result = await oasis.avatar.update({
  id:        avatarId,
  firstName: 'Augusta',
  username:  'countess_lovelace'
  // Only include fields you want to change
});

if (!result.isError) console.log('Profile updated!');

Managing Inventory

Every avatar has a persistent inventory — a list of items they hold across all games and apps. Your app can read it, add to it and query individual items.

javascript
// Fetch the full inventory list
const { result: inventory } = await oasis.avatar.getAvatarInventory();

inventory.forEach(item => {
  console.log(`${item.name} (x${item.quantity}) — ${item.description}`);
});

// Check if avatar already has a specific item (by ID)
const { result: has } = await oasis.avatar.avatarHasItem({ itemId: 'sword-of-light-001' });

// Add an item (e.g. after a purchase or quest reward)
const added = await oasis.avatar.addItemToAvatarInventory({
  itemId:      'health-potion-sm',
  name:        'Small Health Potion',
  description: 'Restores 50 HP',
  quantity:    3
});
💡
Inventory vs NFT wallet

Inventory items are lightweight in-game objects (potions, keys, cosmetics). NFTs live in the avatar's on-chain wallet and represent ownership of unique digital assets. A sword earned in-game might start as an inventory item and be "minted" into an NFT later. See Module 4.

Sessions & Token Management

The SDK handles token storage for you, but you'll sometimes need to inspect or manage sessions directly:

javascript
// Check if currently authenticated
if (oasis.auth.isAuthenticated()) {
  const session = oasis.auth.getSession();
  console.log('Logged in as:', session.username, session.avatarId);
}

// Use a token your server already has (SSR/edge scenarios)
oasis.setToken(existingJwt, { username: 'ada_lovelace', avatarId });

// Create a named session (multi-device tracking)
await oasis.avatar.createAvatarSession({ avatarId, deviceName: 'iPhone 15' });

// Revoke token on logout
await oasis.auth.logout();   // clears local store and calls revoke-token

Password Reset Flow

OASIS has a built-in forgot-password flow your app can hook into:

javascript
// Step 1 — request reset email
await oasis.avatar.forgotPassword({ email: 'ada@example.com' });

// Step 2 — user clicks email link → your app receives the reset token
// Step 3 — submit new password with reset token
await oasis.avatar.resetPassword({
  token:           resetToken,
  password:        'NewSecurePass1!',
  confirmPassword: 'NewSecurePass1!'
});

Awarding XP

Your app can grant experience points for in-game actions. XP automatically increases the avatar's level at thresholds set by the OASIS platform.

javascript
const result = await oasis.avatar.addXp({
  avatarId,
  xpAmount: 500,
  reason:   'Completed the first quest'
});

console.log('New XP total:', result.result.xp);
console.log('New level:',   result.result.level);

Avatar API Quick Reference

← Previous
Quick Start