> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Account Master Data Reference

Reference for the master data format and the models to be imported




## Master Data Format


**JSON**
```json
{
  "version": "2024-07-30",
  "takeOverTypeModels": [
    {
      "type": "[int]Slot Number",
      "metadata": "[string?]Metadata",
      "openIdConnectSetting": {
        "configurationPath": "[string]OpenID Connect Configuration URL",
        "clientId": "[string]Client ID",
        "clientSecret": "[string]Client Secret",
        "appleTeamId": "[string]Apple Developer Team ID",
        "appleKeyId": "[string]Key ID registered with Apple",
        "applePrivateKeyPem": "[string]Private Key received from Apple",
        "doneEndpointUrl": "[string?]Redirect URL after authentication is completed",
        "additionalScopeValues": [
          {
            "key": "[string]Name",
            "value": "[string?]Value"
          }
        ],
        "additionalReturnValues": [
          "[string]Additional claim name returned from OpenID Connect"
        ]
      }
    }
  ]
}
```


|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2024-07-30 | | Master data format version |
| takeOverTypeModels | [List&lt;TakeOverTypeModel&gt;](#takeovertypemodel) |  |  |  |  ~ 1000 items | Takeover Type Model<br>This model defines Takeover Information.<br><br>Takeover Information is used when changing devices or transferring an account across platforms.<br>It consists of a unique string that identifies an individual and a password; by entering the correct combination, a GS2 Account (anonymous account) can be retrieved.<br><br>Multiple sets of Takeover Information can be configured for a single Account.<br>To configure multiple sets, you must assign each one to a different slot.<br>Slots can be specified from 0 to 1024, allowing for up to 1,025 types of Takeover Information to be set.<br><br>A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1.<br>It should be noted that this Takeover Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately. |

## Models

### TakeOverTypeModel

Takeover Type Model

This model defines Takeover Information.

Takeover Information is used when changing devices or transferring an account across platforms.
It consists of a unique string that identifies an individual and a password; by entering the correct combination, a GS2 Account (anonymous account) can be retrieved.

Multiple sets of Takeover Information can be configured for a single Account.
To configure multiple sets, you must assign each one to a different slot.
Slots can be specified from 0 to 1024, allowing for up to 1,025 types of Takeover Information to be set.

A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1.
It should be noted that this Takeover Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| takeOverTypeModelId | string |  | * |  |  ~ 1024 chars | Takeover Type Model GRN<br>* Set automatically by the server |
| type | int |  | ✓ |  | 0 ~ 1024 | Slot Number<br>Specified in the range of 0 to 1024 to distinguish different types of Takeover Information. |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| openIdConnectSetting | [OpenIdConnectSetting](#openidconnectsetting) |  | ✓ |  |  | OpenID Connect Configuration<br>Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Sign in with Apple parameters. |

---

### OpenIdConnectSetting

OpenID Connect Configuration

By registering the settings of an OpenID Connect-compliant IdP, IdP integration can be configured and used as Takeover Information.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| configurationPath | string |  | ✓ |  |  ~ 1024 chars | OpenID Connect Configuration URL<br>The discovery endpoint URL of the OpenID Connect provider. Must follow the well-known format (e.g., https\://example.com/.well-known/openid-configuration). |
| clientId | string |  | ✓ |  |  ~ 1024 chars | Client ID<br>The client ID of the application registered with the IdP. |
| clientSecret | string | {configurationPath} != "https\://appleid.apple.com/.well-known/openid-configuration" | ✓* |  |  ~ 1024 chars | Client Secret<br>* clientSecret is required when the configurationPath is not  "https\://appleid.apple.com/.well-known/openid-configuration", i.e., for other IdP integrations. |
| appleTeamId | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓* |  |  ~ 1024 chars | Apple Developer Team ID<br>The team ID from the Apple Developer account. Required for Sign in with Apple authentication.<br>* Required if configurationPath is "https\://appleid.apple.com/.well-known/openid-configuration" |
| appleKeyId | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓* |  |  ~ 1024 chars | Key ID registered with Apple<br>The key ID registered in the Apple Developer account for Sign in with Apple.<br>* Required if configurationPath is "https\://appleid.apple.com/.well-known/openid-configuration" |
| applePrivateKeyPem | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓* |  |  ~ 10240 chars | Private Key received from Apple<br>The private key in PEM format downloaded from the Apple Developer portal. Required for Sign in with Apple authentication.<br>* Required if configurationPath is "https\://appleid.apple.com/.well-known/openid-configuration" |
| doneEndpointUrl | string |  |  |  |  ~ 1024 chars | Redirect URL after authentication is completed<br>If not specified, the user will be redirected to /authorization/done.<br>The id_token is included as a query parameter. |
| additionalScopeValues | [List&lt;ScopeValue&gt;](#scopevalue) |  |  | [] | 0 ~ 10 items | Additional scopes obtained with OpenID Connect<br>Additional OAuth scopes to request from the IdP beyond the default OpenID Connect scopes. Allows retrieving extra user information during authentication. |
| additionalReturnValues | List&lt;string&gt; |  |  | [] | 0 ~ 10 items | Additional claim name returned from OpenID Connect<br>Additional claim names extracted from the ID token or UserInfo response and included in the authentication result. Specified claims are extracted and returned alongside the standard authentication result. |

---

### ScopeValue

Scope Value

A key-value pair representing an additional OAuth scope value obtained during OpenID Connect authentication. Used to store extra data retrieved from the IdP beyond the standard OpenID Connect claims.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64 chars | Name<br>The scope name that was requested from the IdP during authentication. |
| value | string |  |  |  |  ~ 51200 chars | Value<br>The value returned by the IdP for the corresponding scope. |

---