{"id":29572652,"url":"https://github.com/accelbyte/accelbyte-go-modular-sdk","last_synced_at":"2026-01-20T17:28:59.367Z","repository":{"id":186686227,"uuid":"674533002","full_name":"AccelByte/accelbyte-go-modular-sdk","owner":"AccelByte","description":"AccelByte Go modular SDK","archived":false,"fork":false,"pushed_at":"2025-07-16T00:16:04.000Z","size":34347,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-17T00:49:19.460Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccelByte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-04T07:11:41.000Z","updated_at":"2025-07-16T00:16:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"47014d52-d27b-4cf2-b3fd-d7256b559ef3","html_url":"https://github.com/AccelByte/accelbyte-go-modular-sdk","commit_stats":null,"previous_names":["accelbyte/accelbyte-go-modular-sdk"],"tags_count":530,"template":false,"template_full_name":null,"purl":"pkg:github/AccelByte/accelbyte-go-modular-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-go-modular-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-go-modular-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-go-modular-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-go-modular-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccelByte","download_url":"https://codeload.github.com/AccelByte/accelbyte-go-modular-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-go-modular-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265892500,"owners_count":23845031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T05:10:44.931Z","updated_at":"2026-01-20T17:28:59.359Z","avatar_url":"https://github.com/AccelByte.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AccelByte Modular Go SDK\n\n\u003e :warning: **This [accelbyte-go-modular-sdk](https://github.com/AccelByte/accelbyte-go-modular-sdk) \n\u003e is not to be confused with [accelbyte-go-sdk](https://github.com/AccelByte/accelbyte-go-sdk):** \n\u003e * The former (modular SDK) is **experimental** and is planned to be the sucessor for the latter (monolithic SDK).\n\u003e * The modular SDK allows developers to include only the required modules in projects.\n\u003e * If you are starting a new project, you try to use modular SDK.\n\u003e * If you use monolithic SDK in an existing project, a migration path is available via compatibility layer in modular SDK.\n\u003e * Both monolithic and modular SDK will be maintained for some time to give time for migration until monolithic SDK is deprecated in the future.\n\nA software development kit (SDK) for interacting with AccelByte Gaming Services (AGS) written in Go.\n\nThis SDK was generated from AGS OpenAPI spec files included in the [spec](spec) directory.\n\n## Setup\n\nThis SDK requires `go 1.23` or newer version to be installed.\n\n### Import SDK Project\n\nFor example, add the following to your project's `go.mod`:\n\nInstead of\n```go\nrequire (\n    github.com/AccelByte/accelbyte-go-sdk {VERSION}\n)\n```\nMigrate with\n```go\nrequire (\n    github.com/AccelByte/accelbyte-go-modular-sdk/{service}-sdk {VERSION}\n)\n```\nInstead of importing the whole package, select which AGS service we want to import in the project.\nUse more than one AGS service if necessary.\n\nReplace `{VERSION}` with a specific release version tag. When starting a new project, \nusing the latest release version is recommended.\n\nFor more example, please refer to the [samples](samples) folder.\n\n\u003e NOTE: Here is the exhaustive list of go sdk modules available to be used - [Published Go Modules](./docs/published_go_modules.md)\n\n### Environment Variables\n\nThe following environment variables need to be set when using `ConfigRepository`.\n\n| Name               | Required                                               | Example                          |\n|--------------------|--------------------------------------------------------|----------------------------------|\n| `AB_BASE_URL`      | Yes                                                    | https://test.accelbyte.io        |\n| `AB_CLIENT_ID`     | Yes                                                    | abcdef0123456789abcdef0123456789 |\n| `AB_CLIENT_SECRET` | Yes, but only if you use a confidential `AB_CLIENT_ID` | ab#c,d)ef(ab#c,d)ef(ab#c,d)ef(ab |\n\n### Migrating An Existing Project\n\nTo start migrating an existing project which uses [accelbyte-go-sdk](https://github.com/AccelByte/accelbyte-go-sdk) \nmonolithic package to this [accelbyte-go-modular-sdk](https://github.com/AccelByte/accelbyte-go-modular-sdk) modular package, \nit can be done with minimum effort by importing the AGS service of choice in the go.mod files and \nuse `go build -tags compat` to build it with compatibility layer. After this, the compatibility layer\ncan be removed bit by bit until the project is fully migrated.\n\n## Usage\n\n### Instantiation\n\n```go\n// example for OAuth20 in IAM service\noAuth20Service := iam.OAuth20Service{\n    Client:           factory.NewIamClient(auth.DefaultConfigRepositoryImpl()), \n    ConfigRepository: auth.DefaultConfigRepositoryImpl(), \n    TokenRepository:  auth.DefaultTokenRepositoryImpl(),\n}\n```\n\n## Enable HTTP Logging\n\nTo enable http logging feature, set `ENABLE_LOG` to true in the environment variables.\n\n```\nexport ENABLE_LOG=true\n```\n\n#### With Custom HTTP retry in the client\n\nUse this to get SDK instance with HTTP retry functionality.\n\n```go\ninput := \u0026o_auth2_0.TokenGrantV3Params{\n\t\tPassword:  \u0026password,\n\t\tUsername:  \u0026username,\n\t\tGrantType: o_auth2_0.TokenGrantV3PasswordConstant,\n\t}\ninput.RetryPolicy = \u0026utils.Retry{\n    Transport: OAuth20Service.Client.Runtime.Transport,\n    MaxTries:  utils.MaxTries,\n    Backoff:   utils.NewConstantBackoff(0),\n    RetryCodes: map[int]bool{\n        502: true, // add an error code for bad gateway\n    },\n}\nok, err := OAuth20Service.TokenGrantV3Short(input) // call the wrapper\n```\n\n### Working with Call Response\n\nEvery operation in Go Modular SDK will returns a response object. Use this object to do check whether the call is\nsuccess or not, get the response data or error object.\n\n- `response.IsSuccess` will be `true` if the call is success, otherwise `false`.\n- `response.Data` object is **optional** depending whether the endpoint has response or not.\n- `response.Error\u003cstatus-code\u003e` contains error object if call failed, otherwise null.\n- `response.Unpack` will return the all the responses given by the endpoint.\n- `response.StatusCode` will return the int status code responses given by the endpoint.\n\nKnown errors are available in `errors.go` in each module. E.g\n`\u003cmodule-name\u003e-sdk/pkg/\u003cmodule-name\u003eclientmodels/errors.go`.\n\n```go\nresponse, err := userProfileService.GetMyProfileInfoShort(input)\nif response.Error400 != nil {\n    // do something\n} else {\n    ok := response.Data\n    // do something\n    response.Unpack // do something with the return value\n}\n```\n\n#### Automatic Token Refresh\n\nThe Automatic Token Refresh is invoked by `auth.RefreshTokenScheduler` inside the `login` wrapper with the Default configuration and can be override.\nUse the following to get SDK instance with automatic token refresh functionality which is performed before each HTTP request but only if access token is almost expired.\n\n```go\noAuth20Service = \u0026iam.OAuth20Service{\n    Client:           factory.NewIamClient(auth.DefaultConfigRepositoryImpl()),\n    ConfigRepository: auth.DefaultConfigRepositoryImpl(),\n    TokenRepository:  auth.DefaultTokenRepositoryImpl(),\n    RefreshTokenRepository: \u0026auth.RefreshTokenImpl{ // override the default refresh token. For example, enable the AutoRefresh functionality or change RefreshRate\n        RefreshRate: 0.5, // refresh when 50% of the token’s lifetime remains.\n        AutoRefresh: true, // automatically refresh the token in the background.\n    }\n}\n```\n\nIf no need to customize the behavior, use the default refresh token configuration.\nThe default RefreshRate is `0.8`, which means the SDK will refresh the token when 20% of its lifetime remains.\n\n```go\noAuth20Service = \u0026iam.OAuth20Service{\n    ...\n    RefreshTokenRepository: auth.DefaultRefreshTokenImpl(), // use the default value\n}\n```\nUse the `repository` to access all functions for refresh token.\n\n#### On-demand Refresh Token\n\nThe on-demand refresh token is intended to be used in environment where automatic refresh token cannot work properly e.g. AWS Lambda. The way to initialize it\nis similar to automatic refresh token except the `AutoRefresh` parameter must be set to `false`. After that, `LoginOrRefreshClient` or `LoginOrRefresh` for logging in using client token or username and password respectively can be used before calling any endpoints. These two functions are helper functions for developers to either login or refresh as required.\n\n```go\noAuth20Service = \u0026iam.OAuth20Service{\n    Client:           factory.NewIamClient(auth.DefaultConfigRepositoryImpl()),\n    ConfigRepository: auth.DefaultConfigRepositoryImpl(),\n    TokenRepository:  auth.DefaultTokenRepositoryImpl(),\n    RefreshTokenRepository: \u0026auth.RefreshTokenImpl{\n        RefreshRate: 0.5,\n        AutoRefresh: false, // must be set to false for on demand refresh token\n    },\n}\n...\nerr := oauth.LoginOrRefreshClient(\"clientId\", \"clientSecret\")   // use before calling endpoints, using client token\n...\nerr := oauth.LoginOrRefresh(\"username\", \"password\")     // use before calling endpoints, using username and password\n```\n\n#### Local Token Validation\nLocal token validation is available since version 0.37.0. \nTo enable it, import the package\n```go\nimport (\n    ...\n    \"github.com/AccelByte/accelbyte-go-modular-sdk/services-api/pkg/utils/auth/validator\"\n    ...\n)\n```\nconfigure `authTokenValidator` struct or use the existing one `NewTokenValidator` with the default `localValidationActive` is false. Invoked them with\n```\ntokenValidator := validator.NewTokenValidator(authService, time.Hour)\ntokenValidator.Initialize()\n\nerr = tokenValidator.Validate(accessToken, \u0026requiredPermission, \u0026namespace, nil)\n```\n\nif want to set `localValidationActive` is true, use a `TokenValidator` directly and do this:\n```\ntokenValidator := \u0026validator.TokenValidator{\n\t\tAuthService:     *oAuth20Service,\n\t\tRefreshInterval: time.Hour,\n\n\t\tFilter:                nil,\n\t\tJwkSet:                nil,\n\t\tJwtClaims:             validator.JWTClaims{},\n\t\tJwtEncoding:           *base64.URLEncoding.WithPadding(base64.NoPadding),\n\t\tPublicKeys:            make(map[string]*rsa.PublicKey),\n\t\tLocalValidationActive: true, // set here to true\n\t\tRevokedUsers:          make(map[string]time.Time),\n\t\tRoles:                 make(map[string]*iamclientmodels.ModelRoleResponseV3),\n\t}\n\t\ntokenValidator.Initialize()\n\nerr = tokenValidator.Validate(accessToken, \u0026requiredPermission, \u0026namespace, nil)\n```\n\n## Login\n\n### Login Using Username and Password\n\n```go\nerr := oAuth20Service.Login(username, password)\nif err != nil {\n    return err\n}\n```\n\nYou can also specify the scope you want for `LoginWithScope(...)`. With the `scope` parameter typed as `string`. By default the scope used is `commerce account social publishing analytics` (a space separated value string).\n\n```go\nerr := oAuth20Service.LoginWithScope(username, password, scope)\nif err != nil {\n    return err\n}\n```\n\n### Login Using OAuth Client (Public or Private)\n\n```go\nerr := oAuth20Service.LoginClient(clientId, clientSecret)\nif err != nil {\n    return err\n}\n```\n\nIt’s possible to pass a context created or derived from another method into LoginClientWithContext(ctx, ...), allowing you to carry tracing information or other context-related data through the login process.\n\n```go\nctx := context.Background()\n\nerr := oAuth20Service.LoginClientWihContext(ctx, clientId, clientSecret)\nif err != nil {\n    return err\n}\n```\n\n:bulb: The use of a Public OAuth Client is highly discouraged! Please ensure that you both set the Client ID and Client Secret.\n\n:bulb: There are other `WithContext` variants of the `LoginX` functions in case you want to use a specific context.\n\n## Parse Access Token\nFunctionality to parse the access token is available in `v0.50.0`.\nThe function exist alongside the Login functionality in `OAuth20Service`. To use it, import the package\n```go\nimport (\n    ...\n    \"github.com/AccelByte/accelbyte-go-modular-sdk/services-api/pkg/service/iam\"\n    ...\n)\n```\nGet the token, and use `ParseAccessToken` function. Set the second parameter as `true` if it wants to validate before parse the access token\n```go\n// get the access token string\naccessToken, err := oAuth20Service.GetToken()\nif err != nil {\n    // fail here\n}\n\n// parse the token\nparsedToken, err := oAuth20Service.ParseAccessToken(accessToken, true) // set true here to validate before parse the access token\nif err != nil {\n    // fail here\n}\n```\n- if the boolean is `false`, it will not validate the token at all.\n- if the boolean is `true`, it will validate remotely (call `VerifyTokenV3` endpoint).\n- if the boolean is `true` and call `SetLocalValidation` before `ParseAccessToken`, it will validate locally.\n```go\noAuth20Service.SetLocalValidation(true) // call this also to activate local validation\n\n// parse the token\nparsedToken, err := oAuth20Service.ParseAccessToken(accessToken, true) // set true here to validate before parsing the access token\nif err != nil {\n// fail here\n}\n```\n\n### Interacting with AccelByte Gaming Services HTTP Endpoints\n\nAs an example, we will get current user profile info using [getMyProfileInfo](https://docs.accelbyte.io/api-explorer/#Basic/getMyProfileInfo) endpoint available in [basic](https://docs.accelbyte.io/api-explorer/#Basic) service.\n\n```go\n// Instantiate UserProfile (Basic service) and input model as the global variable\nvar (\n    userProfileService = \u0026basic.UserProfileService{\n        Client:          factory.NewBasicClient(auth.DefaultConfigRepositoryImpl()), \n        TokenRepository: auth.DefaultTokenRepositoryImpl(),\n    }\n    input = \u0026user_profile.GetUserProfileInfoParams{\n        Namespace: namespace,\n    }\n)\n\n// Login using username and password\nerr := oAuth20Service.Login(username, password)\nif err != nil {\n    return err\n}\n\n// Make a call to getMyProfileInfo endpoint through the wrapper\nok, err := userProfileService.GetMyProfileInfoShort(input)\nif err != nil {\n    return err\n}\n```\nThe `basic-sdk` contains 2 directories:\n- `basicclient` contains the logic to make requests.\n- `basicclientmodels` contains the models such as request and response models.\n\nClient must create a struct that implement following interface:\n\n- `ConfigRepository` is responsible to store configuration.\n- `TokenRepository` is responsible to store access token.\n\nFor more details, see [repository](samples/cli/pkg/repository) for the interface and [cli samples](samples/cli/cmd) on how to use it.\n\n### Interacting with AccelByte Gaming Services WebSocket Endpoints\n\nTo interact with AccelByte Gaming Services services which use WebSocket endpoints e.g. AccelByte Gaming Services Lobby\nService, use an existing Initialisation code or implement custom `wsm/ConnectionManager` interface.\n`ConnectionManager` manages WebSocket connection that save, get and close the WebSocket connection. In other words,\nclient should maintain WebSocket connection using `ConnectionManager`.\n\n```go\nconnMgr = \u0026wsm.DefaultConnectionManagerImpl{}\nconn, err := wsm.NewWSConnection(\n    oAuth20Service.ConfigRepository,\n\toAuth20Service.TokenRepository,\n    wsm.WithEnableAutoReconnect(),\n\twsm.WithMessageHandler(lobbyMessageHandler), // do optionals\n)\nif err != nil {\n// error\n}\nlobbyClient := connectionutils.NewLobbyWebSocketClient(conn)\n\n// [optional] do something before Connecting\n\nsuccess, err := lobbyClient.Connect(false) // Connecting\nif err != nil {\n// error\n}\n\nconnMgr.Save(conn)\n\n// CASE Lobby get a notification\nerr = notificationService.GetNotificationMessage()\n// error\n```\n\nFor reference, see [connectionutils_test.go](lobby-sdk/pkg/connectionutils/connectionutils_test.go)\nor [services-api/pkg/wsm/connection.go](services-api/pkg/wsm/connection.go).\n\n### Refresh Token\n```go\ngetToken, errGetToken := oAuth20Service.TokenRepository.GetToken()\n    if errGetToken != nil {\n        // failed to get token\n    }\n\t\nhasExpired := repository.HasTokenExpired(*getToken) // use the repository of the sdk to get the available functions\n```\n\n## Logout\n```go\nerr := oAuth20Service.Logout()\nif err != nil {\n    return err\n}\n```\n\n## FlightID\n\nSince ags/v3.67.0, Go Extend SDK enable support for FlightID transmission during Http request. By default, new flight id\nwill be generated when the sdk is loaded. There will be some case that this default value need to be updated with new\nvalue.\n\n- To update default flight id globally, use following code:\n  ```go\n  utils.GetDefaultFlightID().SetFlightID(\"\u003cnew flight id value\u003e\");\n  ```\n  This will update the default flight id, and will be used by newly created sdk object (this example use \"\n  userProfileService\").\n\n  or\n\n  ```go\n  userProfileService.FlightIdRepository = \u0026utils.FlightIdContainer{Value: \"\u003cnew flight id value\u003e\"}\n  ```\n  This will update the default flight id, and will be used by newly created sdk object (won't affect existing sdk object\n  created before this code get executed).\n- To update flight id value in sdk object, use following code:\n  ```go\n  userProfileService.UpdateFlightId(\"\u003cnew flight id value\u003e\")\n  ```\n  This will update the flight id value stored inside the sdk object. Will be used for all operations executed by the sdk\n  object.\n- To update flight id value for specific operation, use `UpdateFlightId` parameter when building the operation object.\n  ```go\n  // Make a call to GetMyProfileInfo endpoint\n  input := \u0026user_profile.GetMyProfileInfoParams{\n      Namespace: admin,\n  }\n  input.XFlightId = \"\u003cnew flight id value\u003e\"\n  ok, err := userProfileService.GetMyProfileInfoShort(input)\n  ```\n\n## Samples\n\nSample apps are available in the [samples](samples) directory.\n\n## Documentation\n\nReference about AccelByte service endpoints and their corresponding SDK API is available in [docs/operations](docs/operations) directory.\n\nSample app documentations are available in the [docs/samples](docs/samples/) directory.\n\nFor more information on how to use AccelByte services and SDKs, see [docs.accelbyte.io](https://docs.accelbyte.io/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Faccelbyte-go-modular-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccelbyte%2Faccelbyte-go-modular-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Faccelbyte-go-modular-sdk/lists"}