API

Permissions

An API key holds a list of permissions, and so does every token made from it. Each call needs one particular permission, and is answered 404 when the token does not hold it.

How a permission reads

A permission is a path of <resource>:<id> pairs followed by an action:

usr:4:gm:aX9k2Qp:lb:H7fj2Kp:submit

"On account 4, game aX9k2Qp, leaderboard H7fj2Kp: submit." The dashboard writes the shortest form that still names one thing, lb:H7fj2Kp:submit, since ids are unique within their kind.

Wildcards

Pattern	Means
`*` as an id	Every resource of that kind under its parent: `gm:aX9k2Qp:lb:*:submit` is every leaderboard of the game.
`*` as the action	Every action on that resource: `lb:H7fj2Kp:*`.
`**` as the action	Every action on that resource and everything inside it: `gm:aX9k2Qp:**`.
a role as the action	The role's actions, on that resource and everything inside it: `gm:aX9k2Qp:game_client`.

A permission must start with a specific resource. lb:*:submit is refused, because it would mean every leaderboard on Scoreboat, not every leaderboard of yours.

Roles

A role is a named set of actions, granted like one action. A role reaches more as Scoreboat grows: when a new service adds an action to it, keys holding the role can use that action at once.

Role	Name	What it covers
`game_client`	Game client	What a shipped copy of the game needs at runtime, such as submitting and reading scores. Never covers settings or deletion, and grows to include game-client actions from services added later.

Resources and actions

Everything that can be granted, by resource. "Game client" marks the actions the game client role includes.

`usr` Account

The root: your account.

Action	Allows	Game client
`details`	Read account details
`games`	List the games on the account

`gm` Game

Inside usr (Account).

Action	Allows	Game client
`details`	Read game details	Yes
`configure`	Change game settings
`leaderboards`	List the game's leaderboards	Yes
`buckets`	List the game's file buckets	Yes
`realtime`	Connect to the game's rooms	Yes
`player_auth`	Sign players in and register them	Yes
`player_assert`	Vouch for a player the tenant has authenticated itself
`delete`	Delete the game

`lb` Leaderboard

Inside gm (Game).

Action	Allows	Game client
`details`	Read leaderboard settings	Yes
`scores`	Read the score table	Yes
`submit`	Submit new scores	Yes
`submit_for`	Submit scores on behalf of any player
`configure`	Change leaderboard settings
`delete`	Delete the leaderboard

`score` Score

Inside lb (Leaderboard).

Action	Allows	Game client
`details`	Read a single score	Yes
`edit`	Change a score that is already posted
`delete`	Remove a score from the leaderboard

`bkt` File bucket

Inside gm (Game).

Action	Allows	Game client
`details`	Read the bucket's limits and usage	Yes
`files`	Use files as each folder's rules allow	Yes
`admin`	Read, write and delete any file, whatever the folder rules say
`configure`	Change folder rules and delete folders
`delete`	Delete the bucket and everything in it

`pool` Player pool

Inside usr (Account).

Action	Allows	Game client
`details`	Read player pool settings
`players`	List and search the players in the pool
`configure`	Change player pool settings
`delete`	Delete the player pool

`ply` Player

Inside pool (Player pool).

Action	Allows	Game client
`details`	Read a player's account
`edit`	Change a player's account
`ban`	Ban and unban a player
`logout`	Sign a player out everywhere
`delete`	Delete and restore a player

Asking for less

When getting a token, a client may name the permissions it wants, and the token carries only those of them the key holds. A tool that only reads scores can ask for just that, even when its key can do more. See Authentication.

Scoreboat

Permissions

How a permission reads

Wildcards

Roles

Resources and actions

usr Account

gm Game

lb Leaderboard

score Score

bkt File bucket

pool Player pool

ply Player