Players

The player API has two halves.

The first is what a game uses, with the key it ships with, to make somebody a signed-in player: as a guest, with a username and password, or with a ticket from your own server. Every one of these calls sits under the game and needs only its player_auth action, which the game client role includes. Signing in answers with a new token: the token the call was made with, plus the player. Use it in place of the old one from then on.

The second half is yours, for your own server: vouching for players you have signed in yourself (assert), and looking after the players you have: listing, banning, signing out and deleting them. None of that is in the game client role, because a key that can do it should not ship inside a game.

Wrong sign-in details, or a call that needs a signed-in player when none is, answer 403. Too many failed attempts answer 429 for a while.

Objects

Shapes that more than one endpoint answers with. Fields marked as the tenant's appear only in answers to your own server's calls.

Player

Player {
  id: string,                   // public, and safe to show anyone
  display_name: string,
  username: string | null,
  email: string | null,
  email_verified: boolean,
  guest: boolean,               // no account: signs in with a saved secret
  created: string,              // ISO datetime

  // Only in answers to the tenant's own calls:
  pool: string,                 // the player pool's id
  external_id: string | null,   // your id, for a player your server vouched for
  last_seen: string | null,     // ISO datetime
  banned: boolean,
  ban_reason: string,
  deleted: boolean,
}

/api/gm/<game_id>/player/guest/

With no secret, makes a new guest and answers with the secret that is their only claim on the account: it is shown this once. With a secret, signs that guest in again.

POST

Answers 201 for a new guest, with the secret they sign in again with, which is not shown again. Keep it on the device:

{
  player: Player,
  token: string,
  expires_at: int,              // Unix seconds
  refresh_token: string,
  secret: string,               // only for a new guest
}

Answers 200 when a secret signed an existing guest in, without secret.

/api/gm/<game_id>/player/register/

Makes an account with a username and password, and optionally an email and display_name. Called while signed in as a guest, it turns that guest into the account instead, keeping everything they have done.

POST

Answers 201:

{
  player: Player,
  token: string,                // the new bearer token: use it from now on
  expires_at: int,              // when the token runs out, in Unix seconds
  refresh_token: string,        // trade it at player/refresh/ for a new token
}

/api/gm/<game_id>/player/login/

Either a login (a username or an email address) and a password, or a ticket the tenant's own server issued for a player it authenticated.

POST

Answers:

{
  player: Player,
  token: string,                // the new bearer token: use it from now on
  expires_at: int,              // when the token runs out, in Unix seconds
  refresh_token: string,        // trade it at player/refresh/ for a new token
}

/api/gm/<game_id>/player/refresh/

POST

Answers:

{
  player: Player,
  token: string,                // the new bearer token
  expires_at: int,              // Unix seconds
}

The refresh token stays the same, and keeps working until the session ends.

/api/gm/<game_id>/player/logout/

POST

Answers:

{ signed_out: true }

/api/gm/<game_id>/player/me/

GET

Answers a Player.

PATCH

Answers the changed Player.

/api/gm/<game_id>/player/password/forgot/

POST

Answers, whether or not a mail was sent:

{ sent: true }

/api/gm/<game_id>/player/password/reset/

POST

Answers:

{ reset: true }

/api/gm/<game_id>/player/email/verify/

POST

Answers, when it mailed a code:

{ sent: true }

and the Player, with email_verified true, when it took one.

/api/gm/<game_id>/player/assert/

The tenant's server saying "this is external_id, and I have checked". The player is made on first sight. The answer is a ticket for the server to pass to the game client, which trades it in with its own key; it is good once, for two minutes.

POST

Answers 201 when the player is new, 200 when they were known:

{
  player: Player,               // with the fields only the tenant sees
  ticket: string,               // for the game client's player/login/
  expires_at: int,              // Unix seconds
}

/api/pool/<pool_id>/players/

search matches the start of an id, username, display name, email or external id. state is active (default), banned, deleted or all. limit and offset page through them.

GET

Answers:

{
  pool: string,                 // the pool's id
  count: int,
  offset: int,
  limit: int,
  next_offset: int | null,      // null on the last page
  players: [Player],            // with the fields only the tenant sees
}

/api/ply/<player_id>/

GET

Answers the Player, with the fields only the tenant sees.

PATCH

Answers the changed Player, with the fields only the tenant sees.

DELETE

Answers the Player, now deleted, or when permanent:

{
  deleted: string,              // the player's id
  permanent: true,
}

/api/ply/<player_id>/restore/

POST

Answers the restored Player, with the fields only the tenant sees.

/api/ply/<player_id>/ban/

POST

Answers the banned Player, with the fields only the tenant sees.

DELETE

Answers the Player, no longer banned, with the fields only the tenant sees.

/api/ply/<player_id>/logout/

POST

Answers the Player, with the fields only the tenant sees.