Server-side Integration Guide

Overview

This guide walks through the typical server-side integration flow for third-party applications connecting to AWorld Lab APIs. It covers the complete lifecycle: authenticating, registering users, and operating on their behalf.

Technical note: This integration uses the OAuth2 client credentials grant.

Audience: Backend developers integrating AWorld Lab from a server-side application.

Why two sets of credentials? AWorld Lab separates administrative operations (Dashboard API) from consumer operations (App API) for security. Each API context issues its own tokens with minimal scopes, ensuring that a consumer token cannot perform admin actions and vice versa. This means your integration will use two distinct OAuth2 clients.

Prerequisites

Before starting, ensure you have received the following from your AWorld administrator:

Item	Description
Dashboard credentials	`clientId` and `clientSecret` for the Dashboard (Admin) API
App credentials	`clientId` and `clientSecret` for the App (Consumer) API
Workspace ID	Your isolated workspace identifier

Each API context requires its own set of credentials. Dashboard credentials cannot be used for App API calls and vice versa.

Integration Flow

The diagram below illustrates the typical integration scenario: a third-party client registers a user via the Dashboard API, then operates on behalf of that user via the App API.

Step 1: Authenticate with Dashboard Credentials

Obtain a server-side access token for the Dashboard (Admin) API using the OAuth2 client credentials flow.

Step 2: Register User via Dashboard API

Use the Dashboard token to create a user in your AWorld workspace. This is an administrative operation — it registers the user within the AWorld platform so they can participate in missions, leaderboards, and other gamification features.

Tip: If you provide an externalId (your system's user identifier), you can later use the x-external-user-id header instead of x-user-id when calling the App API, avoiding the need to store AWorld's internal user IDs.

Step 3: Authenticate with App Credentials

Obtain a separate server-side access token for the App (Consumer) API. This uses different credentials than Step 1.

Step 4: Operate on Behalf of User

With the App token, call the Consumer API using a delegation header to act as a specific user.

User Impersonation Details

Server-side tokens represent a machine, not a user. To perform user-scoped operations on the App API, you must identify which user you are acting on behalf of via a delegation header.

Available Headers

Header	Description	Resolves by
`x-user-id`	AWorld internal user ID (returned when creating the user)	Primary key lookup
`x-external-user-id`	Your system's user identifier (set via `externalId` at user creation)	GSI query on `externalId`

Rules

The two headers are mutually exclusive — sending both returns 400 Bad Request.

On endpoints that require delegation, omitting both headers returns 401 Unauthorized.

Some endpoints support optional delegation — the request succeeds without the header, but providing it scopes the response to the specified user.

How It Works

When a valid delegation header is provided, the platform:

Resolves the user from the database (by internal ID or external ID)

Enriches the server-side token claims with the user's userId, principalId, lang, and timezone

Passes the enriched claims to downstream authorization and data-scoping logic

This means the API behaves as if the request came from the user themselves, with full workspace isolation and permission checks.

Token Management

Server-side access tokens expire after 1 hour. Since the token endpoint is an OAuth2 standard flow, you should cache tokens and refresh them before expiry.

Complete Integration Example

Putting it all together — a complete flow that registers a user and retrieves their profile:

Troubleshooting

Error	Cause	Solution
`401 Unauthorized` on token request	Invalid client credentials	Verify you're using the correct `clientId`/`clientSecret` for the target API context
`401 Unauthorized` on API call	Token expired or wrong context	Check token expiry; ensure Dashboard token is used for `/dashboard/` and App token for `/app/`
`401 Unauthorized` with delegation header	User not found or delegation required	Verify the user ID is correct and the user exists in the workspace
`400 Bad Request` with delegation headers	Both `x-user-id` and `x-external-user-id` sent	Use only one delegation header per request
`403 Forbidden`	Insufficient scope or wrong role	Check token scopes match the API context; Dashboard requires admin/editor role
`409 Conflict` on user creation	User already exists	The user was already registered — retrieve their details instead

Overview#

Prerequisites#

Integration Flow#

Step 1: Authenticate with Dashboard Credentials#

Step 2: Register User via Dashboard API#

Step 3: Authenticate with App Credentials#

Step 4: Operate on Behalf of User#

User Impersonation Details#

Available Headers#

Rules#

How It Works#

Token Management#

Complete Integration Example#

Troubleshooting#