OASIS Learn / Module 1
Beginner ⏱ 15 min

Quick Start — Your First API Call

Install the WEB4 SDK, register an account, authenticate and read back your avatar profile. You'll understand the OASIS response envelope and be ready to build.

What you'll build

  • A small Node.js or browser script that registers a new OASIS avatar
  • Authenticates and retrieves a JWT session token
  • Fetches the avatar profile and prints karma score

Prerequisites

  • Node.js 18+ (or any modern browser — the SDK is isomorphic)
  • Basic JavaScript knowledge — you don't need to know OASIS yet
  • An email address for registration

Step 1 — Install the SDK

The @oasisomniverse/web4-api package covers the complete WEB4 API surface: Avatar, Auth, Karma, NFT, Wallet, Data, Map, Search, HyperDrive, and more. It works in Node 18+ and any modern browser.

terminal
npm install @oasisomniverse/web4-api

For a browser-only project with no build step, use the bundled IIFE script served from the OPORTAL or a CDN:

html
<!-- The global OASISWeb4 object is exposed after this loads -->
<script src="https://oportal.oasisomniverse.one/assets/js/oasis-web4-sdk.js"></script>
📡
Live API endpoint

The default base URL baked into the SDK is https://api.oasisweb4.one. You can point at the staging environment by passing baseUrl: 'https://api-dev.oasisweb4.one' to the constructor.

Step 2 — Initialise the Client

Create a single OASISClient instance and re-use it across your app. It manages JWT storage automatically.

oasis.js
import { OASISClient } from '@oasisomniverse/web4-api';

// Default base URL: https://api.oasisweb4.one
export const oasis = new OASISClient();

// Or with explicit config:
export const oasis = new OASISClient({
  baseUrl: 'https://api.oasisweb4.one',  // Live WEB4 API
  persistSession: true               // Saves JWT to localStorage
});
💡
Session persistence

With persistSession: true the JWT is saved to localStorage (browser) or an in-memory store (Node). The client will automatically attach it to every subsequent request — you don't need to think about tokens.

Step 3 — Register an Avatar

Every user of every app built on OASIS shares one identity — their Avatar. If your users will create accounts from within your app, call oasis.auth.register(). If they already have an OASIS account (from another OApp, OPORTAL, or Our World) they can just log in.

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

const result = await oasis.auth.register({
  firstName:       'Ada',
  lastName:        'Lovelace',
  email:           'ada@example.com',
  password:        'SecurePassw0rd!',
  confirmPassword: 'SecurePassw0rd!',
  username:        'ada_lovelace',     // optional; defaults to email
  avatarType:      'User',             // 'User' | 'Wizard' | 'God'
  acceptTerms:     true
});

if (result.isError) {
  console.error('Registration failed:', result.message);
} else {
  console.log('Registered!', result.session.avatarId);
  // JWT is now stored automatically — no extra steps needed
}

The OASISResult envelope

Every response from the SDK follows a consistent shape:

json (response shape)
{
  "isError": false,
  "message": "Avatar registered successfully.",
  "result": { /* the Avatar object */ },
  "detailedMessage": ""
}

Always check result.isError before using result.result. The SDK normalises all response keys to camelCase regardless of how the server serialises them.

Step 4 — Log In

Use an email address or username — the OASIS authenticate endpoint accepts both.

login.js
import { oasis } from './oasis.js';

const result = await oasis.auth.login({
  username: 'ada@example.com',  // email or username both work
  password: 'SecurePassw0rd!'
});

if (result.isError) {
  console.error('Login failed:', result.message);
  return;
}

const { avatarId, username, email, jwtToken } = result.session;
console.log(`Welcome back, ${username}! (ID: ${avatarId})`);

Step 5 — Fetch the Avatar Profile

Once authenticated, you can read the full avatar detail — including karma score, level, title, inventory and more.

profile.js
import { oasis } from './oasis.js';

// After login, the avatarId is in the stored session
const { avatarId } = oasis.auth.getSession();

const detail = await oasis.avatar.getAvatarDetail({ id: avatarId });

if (!detail.isError) {
  const avatar = detail.result;
  console.log('Username:', avatar.username);
  console.log('Karma:', avatar.karma);
  console.log('Level:', avatar.level);
  console.log('XP:', avatar.xp);
}

Step 6 — Putting It All Together

Here's a self-contained script you can run with node quickstart.mjs:

quickstart.mjs
import { OASISClient } from '@oasisomniverse/web4-api';

const oasis = new OASISClient();

// 1. Log in (assumes account already exists)
const login = await oasis.auth.login({
  username: process.env.OASIS_USER,
  password: process.env.OASIS_PASS
});

if (login.isError) throw new Error(login.message);

const { avatarId } = login.session;
console.log('✓ Authenticated. Avatar ID:', avatarId);

// 2. Fetch full avatar detail
const { result: avatar } = await oasis.avatar.getAvatarDetail({ id: avatarId });
console.log('✓ Avatar:', avatar.username, '| Karma:', avatar.karma, '| Level:', avatar.level);

// 3. Check karma score
const { result: karmaStats } = await oasis.karma.getKarmaStats({ avatarId });
console.log('✓ Karma stats:', karmaStats);

// 4. Log out cleanly
await oasis.auth.logout();
console.log('✓ Session revoked.');
terminal
$ OASIS_USER=ada@example.com OASIS_PASS=SecurePassw0rd! node quickstart.mjs
✓ Authenticated. Avatar ID: 3f8a9b12-...
✓ Avatar: ada_lovelace | Karma: 0 | Level: 1
✓ Karma stats: { total: 0, positive: 0, negative: 0 }
✓ Session revoked.
🌍
Real-world use case — Single Sign-On across your app suite

A studio building three games on OASIS (a mobile RPG, a web strategy game and a VR experience) uses the same oasis.auth.login() call in all three. Players log in once and carry their avatar, karma, inventory and wallet across all three titles with zero extra integration work. This is the OASIS SSO promise.

Error Handling Patterns

All SDK methods return an OASISResult and never throw unless there's a network failure. The recommended pattern:

javascript
async function safeLogin(username, password) {
  try {
    const result = await oasis.auth.login({ username, password });
    if (result.isError) {
      // API-level error (wrong credentials, account locked, etc.)
      console.warn('Login error:', result.message);
      return null;
    }
    return result.session;
  } catch (err) {
    // Network/fetch error
    console.error('Network error:', err.message);
    return null;
  }
}

What's Next?

You've made your first authenticated OASIS API call. Next up:

← Previous
Overview