NEOLearn

GameRuntimeService

The game-facing side of configs and secrets: a running game (its game token) or its own servers (a server key).

Updated October 21, 2026

On this page

The game-facing side: a running game (its session's game token) or the game's own servers (a server key, Authorization: Bearer neosk_...). Every method is a POST with a JSON body; see the overview for the protocol, authentication and errors.

Summary#

MethodAuthDescription
GetConfigGame token or server keyEvery config value of the caller's game. Game tokens and server keys.
GetSecretServer keyA secret's value. Server keys only: a player's game token never reads secrets (peer-to-peer hosts are players' devices).
GrantGame token or server keyThe only way a running game gives a player something of value. Game tokens of the session's authority (its host, else the member who joined first) for players in that session, and server keys for players in any open session of the game. The request names a rule the game's team declared; the platform checks the rule, its event, amount, caps and precondition, then grants, refuses or quarantines it. Retries with the same request_id get the first answer.
SpendCurrencyGame token or server keyTakes in-game currency from a player (never below zero). Currency only goes up through Grant: the data stores that hold it (currency.<name>) refuse a game's own writes.
GetCurrencyBalanceGame token or server keyA player's balance of an in-game currency.
ListGrantRulesGame token or server keyThe rules the game may grant by (enabled ones).
ListPendingReceiptsGame token or server keyA player's purchase receipts for the game's products that no grant has spent yet (what a purchase_receipt rule takes), oldest first.
GetFriendsNoneSocial (SOC-5). A player's own game token for themselves; the session's authority (or a server key) for players in the session (any open session of the game). The player's friends: who they are, and whether each is in this session or this game now (friends who hide their online status are never shown as playing).
IsFriendsWithNone
GetGroupRankNoneThe player's rank in a group (0 and empty: not a member), for gating admin tools, team colours or VIP areas.
SendGameInviteNoneInvites a friend of the player to the player's session, as the player (the same rules and limits as inviting from the app: friends only, no blocks, the host's join setting, at most 10 invites in 10 minutes). The game should only call it when the player asked to invite.
GetPartyNoneThe player's party (empty when they're not in one), so a game can keep parties together.

Methods#

GetConfig#

Every config value of the caller's game. Game tokens and server keys.

HTTP
POST /neo.platform.v1.GameRuntimeService/GetConfig
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: GetRuntimeConfigRequest. Response: RuntimeConfig.

GetSecret#

A secret's value. Server keys only: a player's game token never reads secrets (peer-to-peer hosts are players' devices).

HTTP
POST /neo.platform.v1.GameRuntimeService/GetSecret
Content-Type: application/json

Auth: One of the game's server keys (Authorization: Bearer neosk_...). Never a player's game token.

Request: GetRuntimeSecretRequest. Response: RuntimeSecret.

Grant#

The only way a running game gives a player something of value. Game tokens of the session's authority (its host, else the member who joined first) for players in that session, and server keys for players in any open session of the game. The request names a rule the game's team declared; the platform checks the rule, its event, amount, caps and precondition, then grants, refuses or quarantines it. Retries with the same request_id get the first answer.

HTTP
POST /neo.platform.v1.GameRuntimeService/Grant
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: RuntimeGrantRequest. Response: RuntimeGrantResponse.

SpendCurrency#

Takes in-game currency from a player (never below zero). Currency only goes up through Grant: the data stores that hold it (currency.<name>) refuse a game's own writes.

HTTP
POST /neo.platform.v1.GameRuntimeService/SpendCurrency
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: SpendCurrencyRequest. Response: CurrencyBalance.

GetCurrencyBalance#

A player's balance of an in-game currency.

HTTP
POST /neo.platform.v1.GameRuntimeService/GetCurrencyBalance
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: CurrencyBalanceRequest. Response: CurrencyBalance.

ListGrantRules#

The rules the game may grant by (enabled ones).

HTTP
POST /neo.platform.v1.GameRuntimeService/ListGrantRules
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: ListRuntimeGrantRulesRequest. Response: ListGrantRulesResponse.

ListPendingReceipts#

A player's purchase receipts for the game's products that no grant has spent yet (what a purchase_receipt rule takes), oldest first.

HTTP
POST /neo.platform.v1.GameRuntimeService/ListPendingReceipts
Content-Type: application/json

Auth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).

Request: PendingReceiptsRequest. Response: PendingReceiptsResponse.

GetFriends#

Social (SOC-5). A player's own game token for themselves; the session's authority (or a server key) for players in the session (any open session of the game). The player's friends: who they are, and whether each is in this session or this game now (friends who hide their online status are never shown as playing).

HTTP
POST /neo.platform.v1.GameRuntimeService/GetFriends
Content-Type: application/json

Auth: None.

Request: RuntimePlayerRequest. Response: RuntimeFriends.

IsFriendsWith#

HTTP
POST /neo.platform.v1.GameRuntimeService/IsFriendsWith
Content-Type: application/json

Auth: None.

Request: RuntimeFriendshipRequest. Response: RuntimeFriendship.

GetGroupRank#

The player's rank in a group (0 and empty: not a member), for gating admin tools, team colours or VIP areas.

HTTP
POST /neo.platform.v1.GameRuntimeService/GetGroupRank
Content-Type: application/json

Auth: None.

Request: RuntimeGroupRankRequest. Response: RuntimeGroupRank.

SendGameInvite#

Invites a friend of the player to the player's session, as the player (the same rules and limits as inviting from the app: friends only, no blocks, the host's join setting, at most 10 invites in 10 minutes). The game should only call it when the player asked to invite.

HTTP
POST /neo.platform.v1.GameRuntimeService/SendGameInvite
Content-Type: application/json

Auth: None.

Request: RuntimeInviteRequest. Response: RuntimeInviteResponse.

GetParty#

The player's party (empty when they're not in one), so a game can keep parties together.

HTTP
POST /neo.platform.v1.GameRuntimeService/GetParty
Content-Type: application/json

Auth: None.

Request: RuntimePlayerRequest. Response: RuntimeParty.

Types#

CurrencyBalance#

FieldTypeDescription
currencystring
playerIdstring
balancestring (int64)

CurrencyBalanceRequest#

FieldTypeDescription
currencystring
playerIdstring

GetRuntimeConfigRequest#

No fields: send {}.

GetRuntimeSecretRequest#

FieldTypeDescription
namestring

ListRuntimeGrantRulesRequest#

No fields: send {}.

PendingReceipt#

FieldTypeDescription
receiptIdstringthe purchase's transaction (txn_...): what a purchase_receipt grant names
itemIdstring
itemNamestring
boughtAtstring

PendingReceiptsRequest#

FieldTypeDescription
playerIdstring

PendingReceiptsResponse#

FieldTypeDescription
receiptsarray of PendingReceipt

RuntimeConfig#

FieldTypeDescription
valuesobject (map of string to string)key -> JSON text
revisionstring (int64)the highest config version (changes when any value changes)

RuntimeFriend#

FieldTypeDescription
userUserSummary
inThisSessionbooleanin the caller's session (a server key: in any session of the game)
inThisGamebooleanplaying this game now (any session)

RuntimeFriends#

FieldTypeDescription
friendsarray of RuntimeFriend

RuntimeFriendship#

FieldTypeDescription
friendsboolean

RuntimeFriendshipRequest#

FieldTypeDescription
playerIdstring
userIdstring

RuntimeGrantRequest#

FieldTypeDescription
rulestringthe rule's name
playerIdstringwho gets it (usr_...)
amountstring (int64)currency: how much (items and badges: 1, or 0 for 1)
eventstringthe event that earned it (the rule's event, if it names one)
receiptIdstringa purchase_receipt rule: the purchase's transaction (txn_...)
requestIdstringthe game's idempotency key (1-100 characters)

RuntimeGrantResponse#

FieldTypeDescription
outcomestringgranted, refused or quarantined
reasonstring
grantIdstringthe grant request (grq_...)
balancestring (int64)currency: the player's balance after it

RuntimeGroupRank#

FieldTypeDescription
memberboolean
ranknumber
rolestring

RuntimeGroupRankRequest#

FieldTypeDescription
playerIdstring
groupIdstring

RuntimeInviteRequest#

FieldTypeDescription
playerIdstringwho invites (in a session of this game)
userIdstringthe friend invited

RuntimeInviteResponse#

FieldTypeDescription
sessionIdstringthe session the friend was invited to (ses_...)

RuntimeParty#

FieldTypeDescription
partyIdstringpty_... (empty: not in a party)
leaderUserSummary
membersarray of UserSummary

RuntimePlayerRequest#

FieldTypeDescription
playerIdstring

RuntimeSecret#

FieldTypeDescription
namestring
valuestring

SpendCurrencyRequest#

FieldTypeDescription
currencystring
playerIdstring
amountstring (int64)
requestIdstring

See also#