Getting Started

Overview

AWorld Lab is a multi-tenant gamification platform providing REST APIs across two contexts: App and Dashboard.

Prerequisites

AWorld Lab account (via administrator or sign-up)

Workspace ID for your environment

Basic understanding of REST APIs

Development environment with HTTP client

Account and Workspace Setup

1. Get Access

You'll receive an invitation email with account access instructions.

2. User Types

User: Workspace-scoped user with specific roles (admin, editor, viewer)

3. Workspace ID

Your workspaceId identifies your isolated environment. You'll need this for authentication and API calls.

Example: abc_123-xyz

API Domains

Auth: https://auth.aworld.cloud

API: https://api.aworld.cloud

Dashboard (Admin) API: https://api.aworld.cloud/dashboard/v1/*

App (Consumer) API: https://api.aworld.cloud/app/v1/*

Authentication

AWorld Lab uses AWS Cognito for authentication. Choose the method that fits your use case:

Email OTP (passwordless): For interactive user login via one-time password sent by email. See Quick Start below.

Client Credentials (server-to-server): For backend integration without user interaction. Go directly to the Server-side Integration Guide →

Access tokens contain critical claims including workspaceId, userId, and role. See JWT Token Structure for details.

Quick Start: Email OTP

See Authentication for complete implementation including server-side flows.

API Contexts

AWorld Lab exposes two API contexts with different base URLs:

Context	Base URL	Purpose	Auth Level
Dashboard (Admin/Management API)	`/dashboard/v1/*`	User management, content creation & configuration	Admin/Editor
App (Consumer/User-facing API)	`/app/v1/*`	End-user interactions, content consumption	User

For server-side integrators: If you are integrating from a backend server, "Dashboard" is your management API (create users, configure content) and "App" is your consumer API (act on behalf of users). Each context requires its own set of client credentials (clientId and clientSecret). See the Server-side Integration Guide for a complete walkthrough.

See API Architecture for complete context details and conventions.

Making Your First API Call

REST Example: Get Missions (App Context)

REST Example: Get Single Mission (App Context)

REST Example: Submit Quiz (App Context)

REST Example: Create Mission (Dashboard Context)

REST Example: Pagination

Token Management

Check Token Expiration

Auto-Refresh Access Token

API Wrapper with Auto-Refresh

Common Patterns

Error Handling

Retry Logic with Exponential Backoff

Workspace Context

All API calls are scoped to your workspace via the workspaceId claim in your access token.

Critical: Ensure your token's workspaceId matches the workspace you're accessing. APIs validate this on every request.

Next Steps

Learn Key Concepts

Authentication - Complete auth flows with code

API Architecture - Multi-tenancy, contexts, patterns

Explore API References

OpenAPI Specs: /packages/schemas/{context}/v1/openapi.json

Dashboard: Content creation & configuration

App: User-facing endpoints

Integration Best Practices

Always validate tokens: Check exp claim before use

Implement auto-refresh: Handle token expiration gracefully

Use idempotency keys: Prevent duplicate operations

Enable compression: Include Accept-Encoding: gzip

Handle errors properly: Implement retry with backoff

Request only needed data: Minimize payload size

Use pagination: Don't fetch all items at once

Troubleshooting

Authentication Issues

Issue	Cause	Solution
`401 Unauthorized`	Missing/expired token	Refresh access token
`403 Forbidden`	Insufficient permissions	Check user role in token claims
`WORKSPACE_MISMATCH`	Wrong workspaceId	Verify token's workspaceId claim

API Usage

Issue	Cause	Solution
`400 Bad Request`	Invalid input	Check error details for validation failures
`404 Not Found`	Resource doesn't exist	Verify resource ID
`409 Conflict`	Duplicate resource	Check if resource already exists
`422 Unprocessable`	Semantic validation error	Review business logic constraints

Common Mistakes

Not checking token expiration: Always validate exp claim

Hardcoding workspaceId: Extract from token, don't assume

Missing idempotency keys: Can cause duplicate resources

Ignoring error details: Error responses contain helpful info

Not using pagination: Fetching too much data at once

Support

Documentation: Refer to Authentication and API Architecture docs

OpenAPI Specs: Complete endpoint reference in monorepo

Support: Contact your account administrator

Quick Reference

Auth Domain: https://auth.aworld.cloud

API Domain: https://api.aworld.cloud

API Contexts:

Dashboard (Admin): /dashboard/v1/*

App (Consumer): /app/v1/*

Server-side Credentials (two separate sets required):

Dashboard: clientId/clientSecret for /dashboard/v1/*

App: clientId/clientSecret for /app/v1/*

Token TTL:

Access Token: 1 hour

Refresh Token: 30 days

Required Headers:

Authorization: Bearer {accessToken}
Content-Type: application/json
Accept-Encoding: gzip
x-idempotency-key: {uuid} (for mutations)

Overview#

Prerequisites#

Account and Workspace Setup#

1. Get Access#

2. User Types#

3. Workspace ID#

API Domains#

Authentication#

Quick Start: Email OTP#

API Contexts#

Making Your First API Call#

REST Example: Get Missions (App Context)#

REST Example: Get Single Mission (App Context)#

REST Example: Submit Quiz (App Context)#

REST Example: Create Mission (Dashboard Context)#

REST Example: Pagination#

Token Management#

Check Token Expiration#

Auto-Refresh Access Token#

API Wrapper with Auto-Refresh#

Common Patterns#

Error Handling#

Retry Logic with Exponential Backoff#

Workspace Context#

Next Steps#

Learn Key Concepts#

Explore API References#

Integration Best Practices#

Troubleshooting#

Authentication Issues#

API Usage#

Common Mistakes#

Support#

Quick Reference#