API
API overview
Scoreboat's API is plain HTTP and JSON. A client library wraps it for you; this section is for writing your own client, or calling Scoreboat from your own server.
Base address
Every endpoint is under /api/ on the Scoreboat server you use, for example
https://scoreboat.example.com/api/. The paths in this reference are written
from the server's root.
Making a call
- Get a bearer token with your API key. See Authentication.
- Send it on every call:
text
Authorization: Bearer <token>
- Send bodies as JSON, with
Content-Type: application/json. Answers are always JSON.
A token lasts an hour. Get a new one before it runs out, the same way you got the first.
Who is who
The reference speaks of three parties. The tenant is you: the developer who owns the game, and your own server. A game client is a copy of your game, holding the key it ships with. A player is somebody signed in through a game client.
Ids in paths
Paths name what they act on by its id: /api/lb/<leaderboard_id>/,
/api/bkt/<bucket_id>/, /api/gm/<game_id>/.... Ids are shown in the
dashboard. Players are named by their public player id, which is safe to show
to anyone.
Errors
A refused call answers with a status code and a JSON body holding error, a
sentence meant for a developer, and sometimes more fields:
{"error": "A signed-in player is required to submit a score."}
| Status | Meaning |
|---|---|
| 400 | The request is malformed: missing fields, bad values, not JSON. Fix the request. |
| 401 | The bearer token is missing, expired or no good. Get a new token and try again. |
| 403 | The token is fine, but this is refused: wrong sign-in details, no player signed in, a service turned off, a limit reached. A new token will not change it. |
| 404 | Not found, or your key is not allowed to touch it. The two are deliberately the same, so nobody can find out what exists on someone else's account. |
| 405 | That method is not answered at that path. |
| 429 | Too much: repeated failed sign-ins, or a bucket's downloads for the month used up. Wait and try again. |
If a call you expect to work answers 404, check the key's permissions first.
Paging
Endpoints that list things take limit and offset. Leaderboards and player
lists also answer with next_offset, the offset of the next page, which is
null on the last one. Each endpoint's limits are in its reference.
Reference
The endpoints, one page per service, are generated from Scoreboat's own code, so they always match the server you are reading them on:
- Authentication: getting a token.
- Players: guests, accounts, sign-in, and looking after players.
- Leaderboards: reading and submitting scores.
- Files: buckets, folders, uploads and downloads.
- Rooms: getting into the real-time socket server.
Each endpoint lists the permission it needs for each method, and whether the game client role includes it. See Permissions.