Players
Every environment has its own player table. A player in test and a player in production are different players, even when the same person is behind both.
The Players service is always on: sessions and anything else that names a player need it.
Identities
A player is known by one or more identities. An identity is a provider and a subject: who vouches for the player, and what that provider calls them.
| Provider | Subject | Who signs the player in |
|---|---|---|
server |
Your own id for the player, any string up to 200 characters | Your game server, with a server key |
eos |
The player's Epic Online Services product user id | The game client, with an EOS id token |
The first time a provider and subject are seen in an environment, a player is made for them. After that, the same pair always finds the same player.
A player does not need a GreenMind account, and nothing here assumes one. The console shows whether a player has one linked.
Signing in from your server
Use the server provider when you have your own account system, your own sign-in, or a platform whose identity your server already checks (Steam, a console network, a device id). Your server decides who the player is; the platform takes its word.
curl -X POST https://api.greenmindmedia.com/api/platform/v1/auth/server \
-H "Authorization: Bearer $GM_SERVER_KEY" \
-H "Content-Type: application/json" \
-d '{ "subject": "account-1234", "displayName": "Ada" }'
| Field | Required | Rules |
|---|---|---|
subject |
yes | 1 to 200 characters. Your id for the player |
displayName |
no | 1 to 40 characters after trimming. When given, it replaces the player's current name |
The answer is the player's tokens (see Authentication), with 201 when the sign-in made the player and 200 when it found them. Pass the tokens to the player's game client over your own connection to it.
A new player past what your org's plan allows in the environment is refused with quota-exceeded; players already there keep signing in.
Choose a subject that never changes and means nothing to anyone else: an account id, not an email address or a username the player can change. A new subject is a new player.
Because a server key can sign in any subject, it can act as any of your players. Keep it on your servers.
Signing in with EOS
If your game uses Epic Online Services, the client can sign in without your server.
1. Enable EOS for the environment. In the console, open the environment's sign-in settings, switch EOS on, and enter your EOS client id (the client your game signs in to EOS with). Optionally enter a deployment id: a token from any other deployment is then refused. Do this for each environment that should accept EOS.
2. Sign in from the client. After the player has signed in to EOS Connect, take the id token for their product user (EOS_Connect_CopyIdToken in the EOS SDK) and send it with the environment's app key:
curl -X POST https://api.greenmindmedia.com/api/platform/v1/auth/eos \
-H "Content-Type: application/json" \
-d '{ "appKey": "skyforge_test", "idToken": "eyJraWQiOi..." }'
const response = await fetch('https://api.greenmindmedia.com/api/platform/v1/auth/eos', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ appKey: 'skyforge_test', idToken }),
})
const tokens = await response.json()
The id token is checked against Epic's published signing keys and your client id. The answer is the player's tokens, 201 when the sign-in made the player.
| Refusal | Why |
|---|---|
provider-disabled |
EOS is not switched on for that environment |
unauthorized |
The id token is invalid, expired, for another client, or for another deployment |
quota-exceeded |
A new player, past what your org's plan allows in the environment |
A player signed in with EOS starts with no display name. Set one with PATCH /players/me from the client or PATCH /players/:playerId from your server.
Display names
A display name is what other players see, for example in a lobby. It is 1 to 40 characters after trimming, and it passes through a word filter for names: words the filter does not allow are starred out rather than refused, and the filtered name is what is stored.
A player can change their own name with PATCH /players/me. Your server can change any player's name with PATCH /players/:playerId, or by sending displayName when it signs them in.
A player may have no display name (null). Where a name is needed and there is none, such as a lobby seat, the platform uses Player.
Reading players
Everything about one player is under /players/:playerId: me with the player's own token, and their id with a server key. A player's token naming any id, even its own, is refused with forbidden.
| Route | Credential | Returns |
|---|---|---|
GET /players/me |
Player | The signed-in player |
GET /players/:playerId |
Server | One player of the key's environment |
A player is returned as:
{
"id": "0199a7c3-0b2d-7e11-8c55-5f0e3d9a4b21",
"displayName": "Ada",
"createdAt": "2026-09-29T12:00:00.000Z"
}
Asking for a player of another environment answers not-found, as for a player who does not exist.
In the console, the environment's Players page lists players newest first, and finds them by display name, by player id, or by an identity's exact subject. It also shows each player's identities and when they were last seen (last signed in or refreshed).
Deleting a player
When a player asks you to delete their data, your server calls DELETE /players/:playerId with its server key, which answers 204. Their display name is removed, and so are their identities, so the same id signing in again becomes a new player; so are their saves, tours, game state and what they hold from purchases. Every token they hold stops working.
To end a player's sessions without deleting anything, sign them out everywhere: see Authentication.
Exporting what the platform holds about a player is not yet available in the console or the API. Send such a request to GreenMind with the player's id and environment, as the Data Processing Addendum describes.