Getting Started

Overview

AWorld is a multi-tenant SaaS platform that provides a suite of APIs across three contexts: App, Dashboard, and Portal. This guide will walk you through the initial setup and basic integration steps.

Prerequisites

Before you begin, you'll need:

A AWorld account (provided by your administrator or created through sign-up)

Basic understanding of REST or GraphQL (for API interactions)

Development environment with your preferred language/framework

Account and Workspace Setup

Account Access: You'll receive an invitation email with instructions to access your AWorld account.

User Types:

If you're a Principal (platform-level user), you'll have access to manage multiple accounts.

If you're a User (workspace-level user), you'll have access to a specific workspace within an account.

Workspace Selection: Once logged in, you'll be able to select your workspace if you have access to multiple workspaces.

Authentication

AWorld uses AWS Cognito with a custom domain for authentication. For a complete guide, see Authentication.

Quick Authentication Overview

Register and Sign In:

Use the standard OAuth2 authentication flow

Upon successful authentication, you'll receive access and refresh tokens

Using Tokens:

Include the access token in all API requests as a Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Implement refresh token logic to obtain new access tokens when they expire

API Basics

AWorld provides three API contexts:

Consumer / App Context: For user-facing functionality within a workspace

Admin / Dashboard Context: For management and observability functionality within a workspace

Portal Context: For platform-level operations across accounts and workspaces (principals only)

Making Your First API Call

Here's a simple example of submitting a quiz answer using the App context API:

Next Steps

After completing the initial setup, here are some recommended next steps:

Explore API References:

Consumer/App API

Dashboard API Reference

Portal API Reference

Learn About Key Concepts:

Multi-tenancy

Workspaces

Integration Best Practices:

Implement proper error handling for API calls

Set up token refresh logic to handle expiring access tokens

Use pagination for handling large datasets

Request only the fields you need in GraphQL queries

Common Issues and Troubleshooting

Authentication Issues

Invalid Tokens: Ensure you're using a valid, non-expired access token

Permission Denied: Verify that your user has the necessary permissions for the requested operation

Wrong Context: Confirm you're using the correct API context for your operation

API Usage

GraphQL Syntax: Validate your GraphQL syntax before sending requests

Required Fields: Ensure all required fields are included in your input parameters

Rate Limits: While there are no rate limits in pre-alpha, be mindful of excessive API calls

Support and Resources

Documentation: Refer to this documentation site for detailed information

Support: Contact your account administrator for platform-specific support

GraphQL Resources: Visit graphql.org for GraphQL learning resources

Overview#

Prerequisites#

Account and Workspace Setup#

Authentication#

Quick Authentication Overview#

API Basics#

Making Your First API Call#

Next Steps#

Common Issues and Troubleshooting#

Authentication Issues#

API Usage#

Support and Resources#