Get started with Modular Extend SDK

Last updated on April 2, 2026

Overview​

This article guides you through the fundamentals of creating a project using the Modular Extend SDK — the successor to the monolithic Extend SDK — in multiple supported programming languages.

The Modular Extend SDK allows you to include only the AGS service packages your project actually needs, reducing dependency bloat. A compatibility layer is also available for gradual migration from the monolithic SDK.

Goals​

In this guide you will:

  • Create an application project.
  • Add the Modular Extend SDK packages as project dependencies.
  • Use the Modular Extend SDK to invoke an AGS endpoint.
  • Run the application.

Prerequisites​

In order to start on this guide, you should have:

  • Access to AccelByte Gaming Services (AGS) (demo environment):
    • Use <your environment's domain URL> for the AB_BASE_URL environment variable.
      • Example for AGS Shared Cloud customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Private Cloud customer: https://dev.customer.accelbyte.io
    • Create an OAuth Client with client type Confidential.
      • Use the Client ID value for the AB_CLIENT_ID environment variable.
      • Use the Client Secret value for the AB_CLIENT_SECRET environment variable.
  • AccelByte Python Modular Extend SDK
  • Access to the following tools:
    • Git
    • Python 3.9 or later
    • Python IDE

Create a project​

Create a new solution and a new console project inside the solution using the dotnet CLI.

$ mkdir -p /path/to/mysolution
$ cd /path/to/mysolution
$ dotnet new sln --name mysolution      # Create a new solution: mysolution
$ dotnet new console -o myproject       # Create a new console project: myproject
$ dotnet sln add myproject/myproject.csproj     # Add myproject to mysolution

Add to project dependency​

The Modular Python Extend SDK is distributed as separate pip packages. Install the core package and then add only the AGS service packages your project needs.

# Always required
$ pip install accelbyte-py-sdk-core

# AGS service packages — install only the ones you need
$ pip install accelbyte-py-sdk-service-iam
$ pip install accelbyte-py-sdk-service-basic
# pip install accelbyte-py-sdk-service-<name>  # Add more as needed

# Optional feature packages
$ pip install accelbyte-py-sdk-feat-auth
$ pip install accelbyte-py-sdk-feat-token-validation

# Or install everything at once
# $ pip install accelbyte-py-sdk-all
tip

We recommend using the Modular Python Extend SDK version that matches your AGS version.

Use in code​

  1. Create an SDK instance, log in using client credentials, and call an AGS API in Program.cs.
  2. DefaultConfigRepository reads AB_BASE_URL, AB_CLIENT_ID, and AB_CLIENT_SECRET from environment variables.
// Program.cs

using AccelByte.Sdk.Core;
using AccelByte.Sdk.Core.Net.Http;
using AccelByte.Sdk.Core.Repository;
using AccelByte.Sdk.Api;
using AccelByte.Sdk.Api.Basic.Model;

// Build the SDK instance
IAccelByteSdk sdk = AccelByteSdk.Builder
    .UseDefaultHttpClient()
    .UseDefaultConfigRepository()   // reads AB_BASE_URL, AB_CLIENT_ID, AB_CLIENT_SECRET from env vars
    .UseDefaultTokenRepository()
    .Build();

// Log in using client credentials
bool login = sdk.LoginClient();
if (!login)
{
    Console.WriteLine("Login failed");
    return 1;
}

// Call an AGS endpoint — e.g. getMyProfileInfo from the Basic service
var response = sdk.GetBasicApi().UserProfile.GetMyProfileInfoOp.Execute(sdk.Namespace);
if (response.IsSuccess && response.Data != null)
{
    UserProfilePrivateInfo profileData = response.Data;
    Console.WriteLine($"User ID: {profileData.UserId}");
}
else
{
    Console.WriteLine($"Error: {response.Error?.Message}");
    return 2;
}

// Log out
bool logout = sdk.Logout();
if (!logout)
{
    Console.WriteLine("Logout failed");
    return 1;
}

return 0;

Run the code​

Set the required environment variables and run the code using the Python interpreter.

$ export AB_BASE_URL="<your environment's domain URL>"          # AGS Base URL
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"        # AGS OAuth Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"    # AGS OAuth Client Secret
$ export AB_NAMESPACE="<your namespace>"                        # AGS Namespace
$ python app.py

Migrate from the monolithic SDK​

This section covers how to migrate an existing project that uses the monolithic Extend SDK to the Modular Extend SDK.

tip

The Modular Extend SDK provides a compatibility layer that lets you migrate gradually — your existing code continues to compile while you update it service by service.

Step 1: Clean up obsolete components​

Before migrating, upgrade to the latest monolithic SDK version and remove any usage of deprecated or obsolete classes, methods, and properties. The Modular SDK does not include these.

Step 2: Replace the project dependency​

Remove the monolithic SDK project reference and install the Modular SDK NuGet packages instead.

# Core packages (always required)
$ dotnet add package AccelByte.Sdk.Abstractions
$ dotnet add package AccelByte.Sdk.Core
$ dotnet add package AccelByte.Sdk.Authentication

# Add only the AGS service packages you use
$ dotnet add package AccelByte.Sdk.Api.Iam
$ dotnet add package AccelByte.Sdk.Api.Basic
# dotnet add package AccelByte.Sdk.Api.<ApiName>

# Add the compatibility layer to keep existing code compiling
$ dotnet add package AccelByte.Sdk.Api.Compat

Step 3: Fix namespace and class name changes​

The key breaking changes between the monolithic and modular SDKs are listed below.

SDK class and builder:

MonolithicModular
SDK classAccelByteSDKAccelByteSdk (implements IAccelByteSdk)
SDK builderAccelByteSdkBuilderAccelByteSdkBuilder<T> (implements IAccelByteSdkBuilder<T>)

Namespaces:

ComponentMonolithicModular
HTTP clientAccelByte.Sdk.Core.ClientAccelByte.Sdk.Core.Net.Http
HTTP loggerAccelByte.Sdk.Core.LoggingAccelByte.Sdk.Core.Net.Logging
UtilitiesAccelByte.Sdk.Core.UtilRemoved — moved to extension methods in AccelByte.Sdk.Core
Security(inside class files)AccelByte.Sdk.Core.Security

Fluent API access:

// Monolithic
sdk.Legal.Agreement.RetrieveAgreementsPublicOp.Execute();

// Modular
sdk.GetLegalApi().Agreement.RetrieveAgreementsPublicOp.Execute();

SDK initialization — each default implementation now requires its own namespace:

// Monolithic — single namespace covers everything
using AccelByte.Sdk.Core;

// Modular — include namespaces per component
using AccelByte.Sdk.Core;
using AccelByte.Sdk.Core.Repository;   // for default repositories
using AccelByte.Sdk.Core.Net.Http;      // for HTTP clients

Step 4: Update call response handling​

Every operation call now returns a response object instead of the data directly. Use EnsureSuccess() as a shorthand equivalent to the old behavior.

// Monolithic
List<RetrieveAcceptedAgreementResponse>? response = sdk.GetLegalApi().Agreement
    .RetrieveAgreementsPublicOp.Execute();

// Modular — response object pattern
var response = sdk.GetLegalApi().Agreement.RetrieveAgreementsPublicOp.Execute();
if (response.IsSuccess)
{
    List<RetrieveAcceptedAgreementResponse> data = response.Data;
}

// Modular — shorthand equivalent to monolithic (throws ApiResponseException on failure)
List<RetrieveAcceptedAgreementResponse> data = sdk.GetLegalApi().Agreement
    .RetrieveAgreementsPublicOp.Execute().EnsureSuccess();

Note: The exception type has changed from HttpResponseException to ApiResponseException.

Step 5: Use the compatibility layer (optional)​

If you want the modular SDK to behave like the monolithic SDK while you migrate incrementally, the AccelByte.Sdk.Api.Compat package provides adapter classes that:

  • Expose the original AccelByteSDK class name and fluent interface (sdk.Legal, sdk.Basic, etc.).
  • Re-throw HttpResponseException (translated from ApiResponseException) to keep existing error handling intact.
  • Provide the Helper class in AccelByte.Sdk.Core.Util mapped to extension methods.

Once the compat package is added, your existing code should compile without changes. You can then migrate service by service, removing compat dependencies as you go.

note

The compatibility library does not change the default behavior of on-demand token refresh.

Additional resources​

Last updated on
On this page