Dashboard API Reference (Admin)

Introduction

The Dashboard context provides APIs for administration and management functions, enabling account owners and administrators to configure and monitor their AWorld environments. These APIs are designed for use in administrative interfaces and management tools.

Authentication

The Dashboard context uses the common authentication mechanisms described in Common Features. Dashboard APIs specifically require principal-level or administrator-level permissions.

M2M Implementation Details

For Dashboard context APIs that require "user level" access in machine-to-machine (M2M) flows, you must include the userId of the user to impersonate in a header with every call:

x-user-id: USER_ID_TO_IMPERSONATE

This allows your service to perform actions on behalf of specific users while using client credentials for authentication.

API Endpoints

GraphQL API

The primary API for the Dashboard context is a GraphQL API:

Current Endpoint: https://v1.gql.dashboard.aworld.cloud/graphql

Note: These endpoints are currently exposing internal APIs directly to customers. In the future, all APIs will be accessible through a single reverse proxy, and these endpoints will change.

API Versioning

GraphQL: GraphQL APIs typically use a rolling updates approach without formal versioning until breaking changes occurs. This allows the API to evolve while maintaining backward compatibility. During this pre-alpha stage, more significant changes may occur, but once stable, changes will follow the rolling approach.

REST: REST APIs (when published) will use explicit versioning (e.g., v1, v2). The version numbers will be aligned with GraphQL whenever REST requires updates.

REST APIs

REST APIs will have feature parity with GraphQL APIs but are not published yet:

Future Base URL: TBD

GraphQL Schema

The Dashboard context GraphQL API provides the following main types of operations:

Queries: For retrieving data about users, quizzes, and workspace resources

Mutations: For creating and updating resources

Administrative Context

When authenticated, your API requests operate within the context of:

The authenticated Principal (platform-level user)

The Account you have access to manage

The specific Workspace you are currently working with

Schema Details

Scalar Types

AWSDateTime, AWSDate, AWSTime, AWSTimestamp

AWSEmail, AWSJSON, AWSURL, AWSPhone, AWSIPAddress

Long

Interfaces

User Types

Quiz Types

Common Queries

List Users

Retrieve users in the current workspace:

List Quizzes

Retrieve quizzes with pagination:

Common Mutations

Create User

Create a new user in the current workspace:

Example variables:

{
  "input": {
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "lang": "en",
    "timezone": "Europe/Rome",
    "externalId": "ext-12345"
  }
}

Important: It is strongly recommended to always set an externalId when creating users. This identifier links the user in AWorld to your external system. Without an externalId, it may become impossible to track which user in AWorld corresponds to which user in your platform, especially in scenarios involving user management operations. The externalId should be a stable, unique identifier from your system.

API Features

The Dashboard context implements the common API features described in Common API Features. Please refer to that document for detailed information about:

For the Dashboard context, idempotency is especially critical for administrative operations like user creation and workspace management. For example, if you attempt to create the same user or workspace twice within the 5-minute idempotency window, only the first API call would succeed. This prevents duplicate resource creation during admin operations, which could otherwise cause significant issues.

Pagination

The Dashboard context follows the standard pagination approach described in Common API Features.

For pagination guidelines and best practices, refer to the Common API Features documentation.

Rate Limiting

Please refer to the Common API Features documentation for information about rate limiting.

Administrative Operations

The Dashboard context provides several administrative operations for managing the platform:

User Management

Creating, updating, and deactivating users

Assigning roles and permissions

Managing user access to workspaces

Workspace Management

Creating and configuring workspaces

Setting workspace-specific configurations

Monitoring workspace status and usage

Account Configuration

Managing account settings

Configuring security policies

Setting up integrations with other systems

Best Practices

Use GraphQL variables for dynamic values rather than string interpolation

Request only the fields you need to minimize response size and processing time

Implement error handling to gracefully handle different error scenarios

Use pagination for large result sets to improve performance

Secure administrative endpoints by implementing proper authorization checks

Example Integration

Here's an example of integrating with the Dashboard context API in a JavaScript application:

Additional Resources

GraphQL Documentation

Dashboard Context Schema Explorer (requires authentication)

API Changelog (requires authentication)

Dashboard API Reference (Admin)

Introduction#

Authentication#

M2M Implementation Details#

API Endpoints#

GraphQL API#

API Versioning#

REST APIs#

GraphQL Schema#

Administrative Context#

Schema Details#

Scalar Types#

Interfaces#

User Types#

Quiz Types#

Common Queries#

List Users#

List Quizzes#

Common Mutations#

Create User#

API Features#

Pagination#

Rate Limiting#

Administrative Operations#

User Management#

Workspace Management#

Account Configuration#

Best Practices#

Example Integration#

Additional Resources#