IdentityService
Accounts, sign-in, guests, devices and account settings.
On this page
- Summary
- Methods
- SignUp
- SignIn
- Refresh
- SignOut
- GetMe
- StartGuest
- UpgradeGuest
- ChangePassword
- ChangeUsername
- ListDevices
- RevokeDevice
- SignOutEverywhere
- GetSettings
- UpdateSettings
- DeleteAccount
- IssueScopedToken
- CreateHandoff
- RedeemHandoff
- Types
- AccountSettings
- AuthResponse
- ChangePasswordRequest
- ChangePasswordResponse
- ChangeUsernameRequest
- CreateHandoffRequest
- DeleteAccountRequest
- DeleteAccountResponse
- Device
- GetMeRequest
- GetSettingsRequest
- Handoff
- IssueScopedTokenRequest
- ListDevicesRequest
- ListDevicesResponse
- Me
- RedeemHandoffRequest
- RefreshRequest
- RevokeDeviceRequest
- RevokeDeviceResponse
- ScopedToken
- SignInRequest
- SignOutEverywhereRequest
- SignOutRequest
- SignOutResponse
- SignUpRequest
- StartGuestRequest
- See also
Accounts and sign-in. Every method is a POST with a JSON body; see the overview for the protocol, authentication and errors.
Summary#
| Method | Auth | Description |
|---|---|---|
| SignUp | None | |
| SignIn | None | |
| Refresh | None | |
| SignOut | None | |
| GetMe | Account or guest | |
| StartGuest | None | Play without an account: a guest token with child-safe limits (no chat, no purchases), upgradable to an account that keeps the guest's progress. |
| UpgradeGuest | Account or guest | Turns the signed-in guest into a full account. |
| ChangePassword | Account | Account management. |
| ChangeUsername | Account | |
| ListDevices | Account | Signed-in devices (refresh-token sessions) and revoking them. |
| RevokeDevice | Account | |
| SignOutEverywhere | Account | |
| GetSettings | Account | |
| UpdateSettings | Account | |
| DeleteAccount | Account | Deactivates the account (data deletion follows the retention policy). |
| IssueScopedToken | Account | A short-lived token for an embedded editor (the 3D avatar editor, the Studio), scoped to the calls it makes, instead of the player's access token. The page refreshes it before it expires and hands the new one to the editor (postMessage). |
| CreateHandoff | Account | Single sign-on between the platform's own web hosts (the main host and the studio host have separate browser storage): the signed-in host mints a one-time code for the other host's origin, bound to a PKCE challenge (RFC 7636 S256); the other host redeems it, from that origin and with the verifier, for a session of its own (a new device). Codes work once and live 60 seconds. Target origins are the API's web origins (NEO_WEB_URL, NEO_STUDIO_URL, NEO_WEB_ORIGINS; loopback hosts outside production). |
| RedeemHandoff | None | Spends a handoff code for a new device session. Must be called from the origin the code was made for (the browser's Origin header), with the verifier of its challenge; the code is spent even when the call fails. |
Methods#
SignUp#
POST /neo.platform.v1.IdentityService/SignUp
Content-Type: application/jsonAuth: None.
Request: SignUpRequest. Response: AuthResponse.
SignIn#
POST /neo.platform.v1.IdentityService/SignIn
Content-Type: application/jsonAuth: None.
Request: SignInRequest. Response: AuthResponse.
Refresh#
POST /neo.platform.v1.IdentityService/Refresh
Content-Type: application/jsonAuth: None.
Request: RefreshRequest. Response: AuthResponse.
SignOut#
POST /neo.platform.v1.IdentityService/SignOut
Content-Type: application/jsonAuth: None.
Request: SignOutRequest. Response: SignOutResponse.
GetMe#
POST /neo.platform.v1.IdentityService/GetMe
Content-Type: application/jsonAuth: A signed-in account or a guest.
Also callable with a scoped token: studio.
Request: GetMeRequest. Response: Me.
StartGuest#
Play without an account: a guest token with child-safe limits (no chat, no purchases), upgradable to an account that keeps the guest's progress.
POST /neo.platform.v1.IdentityService/StartGuest
Content-Type: application/jsonAuth: None.
Request: StartGuestRequest. Response: AuthResponse.
UpgradeGuest#
Turns the signed-in guest into a full account.
POST /neo.platform.v1.IdentityService/UpgradeGuest
Content-Type: application/jsonAuth: A signed-in account or a guest.
Request: SignUpRequest. Response: AuthResponse.
ChangePassword#
Account management.
POST /neo.platform.v1.IdentityService/ChangePassword
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: ChangePasswordRequest. Response: ChangePasswordResponse.
ChangeUsername#
POST /neo.platform.v1.IdentityService/ChangeUsername
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: ChangeUsernameRequest. Response: Me.
ListDevices#
Signed-in devices (refresh-token sessions) and revoking them.
POST /neo.platform.v1.IdentityService/ListDevices
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: ListDevicesRequest. Response: ListDevicesResponse.
RevokeDevice#
POST /neo.platform.v1.IdentityService/RevokeDevice
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: RevokeDeviceRequest. Response: RevokeDeviceResponse.
SignOutEverywhere#
POST /neo.platform.v1.IdentityService/SignOutEverywhere
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: SignOutEverywhereRequest. Response: SignOutResponse.
GetSettings#
POST /neo.platform.v1.IdentityService/GetSettings
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: GetSettingsRequest. Response: AccountSettings.
UpdateSettings#
POST /neo.platform.v1.IdentityService/UpdateSettings
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: AccountSettings. Response: AccountSettings.
DeleteAccount#
Deactivates the account (data deletion follows the retention policy).
POST /neo.platform.v1.IdentityService/DeleteAccount
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: DeleteAccountRequest. Response: DeleteAccountResponse.
IssueScopedToken#
A short-lived token for an embedded editor (the 3D avatar editor, the Studio), scoped to the calls it makes, instead of the player's access token. The page refreshes it before it expires and hands the new one to the editor (postMessage).
POST /neo.platform.v1.IdentityService/IssueScopedToken
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: IssueScopedTokenRequest. Response: ScopedToken.
CreateHandoff#
Single sign-on between the platform's own web hosts (the main host and the studio host have separate browser storage): the signed-in host mints a one-time code for the other host's origin, bound to a PKCE challenge (RFC 7636 S256); the other host redeems it, from that origin and with the verifier, for a session of its own (a new device). Codes work once and live 60 seconds. Target origins are the API's web origins (NEO_WEB_URL, NEO_STUDIO_URL, NEO_WEB_ORIGINS; loopback hosts outside production).
POST /neo.platform.v1.IdentityService/CreateHandoff
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: CreateHandoffRequest. Response: Handoff.
RedeemHandoff#
Spends a handoff code for a new device session. Must be called from the origin the code was made for (the browser's Origin header), with the verifier of its challenge; the code is spent even when the call fails.
POST /neo.platform.v1.IdentityService/RedeemHandoff
Content-Type: application/jsonAuth: None.
Request: RedeemHandoffRequest. Response: AuthResponse.
Types#
AccountSettings#
Privacy and preferences. Who-can values: everyone, friends, nobody.
| Field | Type | Description |
|---|---|---|
whoCanMessage | string | |
whoCanFriend | string | |
whoCanJoin | string | |
showOnlineStatus | boolean, optional | |
emailNotifications | boolean, optional | |
theme | string |
AuthResponse#
| Field | Type | Description |
|---|---|---|
accessToken | string | Ed25519 JWT, short-lived. |
refreshToken | string | |
expiresInSeconds | string (int64) | |
me | Me |
ChangePasswordRequest#
| Field | Type | Description |
|---|---|---|
currentPassword | string | |
newPassword | string |
ChangePasswordResponse#
Other devices are signed out; this device gets fresh tokens.
| Field | Type | Description |
|---|---|---|
auth | AuthResponse |
ChangeUsernameRequest#
| Field | Type | Description |
|---|---|---|
newUsername | string | |
password | string |
CreateHandoffRequest#
| Field | Type | Description |
|---|---|---|
targetOrigin | string | The origin the code is for, e.g. "https://studio.neoengine.io". |
codeChallenge | string | base64url(SHA-256(code_verifier)) without padding: 43 characters. |
DeleteAccountRequest#
| Field | Type | Description |
|---|---|---|
password | string |
DeleteAccountResponse#
No fields: send {}.
Device#
| Field | Type | Description |
|---|---|---|
id | string | |
label | string | From the client descriptor (e.g. "Web · Chrome", "Desktop · macOS"). |
createdAt | string | |
lastUsedAt | string | |
current | boolean |
GetMeRequest#
No fields: send {}.
GetSettingsRequest#
No fields: send {}.
Handoff#
| Field | Type | Description |
|---|---|---|
code | string | The one-time code (goes in the URL fragment, never a query string). |
expiresIn | number | Seconds until it expires. |
IssueScopedTokenRequest#
| Field | Type | Description |
|---|---|---|
scope | string | "avatar" (AvatarService) or "studio" (the Studio's CatalogService calls, GetMe). |
ListDevicesRequest#
No fields: send {}.
ListDevicesResponse#
| Field | Type | Description |
|---|---|---|
devices | array of Device |
Me#
| Field | Type | Description |
|---|---|---|
user | UserSummary | |
ageBand | AgeBand (enum) | |
createdAt | string | |
guest | boolean |
RedeemHandoffRequest#
| Field | Type | Description |
|---|---|---|
code | string | |
codeVerifier | string | The verifier whose S256 challenge the code was made with (43-128 characters). |
RefreshRequest#
| Field | Type | Description |
|---|---|---|
refreshToken | string |
RevokeDeviceRequest#
| Field | Type | Description |
|---|---|---|
deviceId | string |
RevokeDeviceResponse#
No fields: send {}.
ScopedToken#
| Field | Type | Description |
|---|---|---|
token | string | |
expiresIn | number | Seconds until it expires. |
SignInRequest#
| Field | Type | Description |
|---|---|---|
username | string | |
password | string |
SignOutEverywhereRequest#
No fields: send {}.
SignOutRequest#
| Field | Type | Description |
|---|---|---|
refreshToken | string |
SignOutResponse#
No fields: send {}.
SignUpRequest#
| Field | Type | Description |
|---|---|---|
username | string | |
password | string | |
birthdate | string | YYYY-MM-DD; sets the age band (never shown to others). |
displayName | string |
StartGuestRequest#
No fields: send {}.