Beacon Open Hosting API
The Beacon Open Hosting API is a JSON-based REST API developers can implement to allow their users to control their servers with Beacon.
Getting Started
When a user wishes to link your service with their Beacon account, they need two things from you: an authentication token and discovery endpoint.
Authentication Tokens
Beacon will use static authentication tokens. How they are created is entirely up to the implementor. A random string at least 64 of printable characters is recommended. Some implementors will prefix these tokens make their purpose more recognizable. The user’s Beacon account will store these tokens encrypted at rest. The implementor may choose to make them expire, but it is recommended to keep their lifespan very long if not infinite. The user will need to delete and replace expired tokens, which is an inconvenience. The user’s computer will make all requests to the API, so whitelisting the token to Beacon’s IP addresses will be counter productive.
The authentication will be sent to the implementing server in the Authorization header using the KEY scheme. For example: Authorization: KEY secretToken.
The Discovery Object
The very first thing Beacon will do is send a request to the provided discovery endpoint. The returned payload informs Beacon where to find the rest of the API endpoints. This allows relocation the API as needed, such as for versioning or region control. This request is authenticated, so the implementor may choose to send different discovery responses to different users.
The object returned by the discovery endpoint should conform to the following spec:
| Key | Type | Required | Description |
|---|---|---|---|
| baseUrl | String | Yes | The full base url to call for each request. Beacon will strip a trailing / from this value if it exists. |
| capabilities | Array | No | A list of features this API supports. If not included, all features are implicitly supported. See Capabilities below. |
| user | Object | No | If supplied, must contain keys id and name. See The User Object below for more details. |
Capabilities
| Key | Notes |
|---|---|
| status | The host supports checking the status of the server. |
| restarts | The host supports starting and stopping the server. Ignored if status is not included. |
| stopMessages | The host can send a customized stop message to the server when stopping. Ignored if status is not included. |
| fullBackups | The host can manually trigger a full backup of both the save data and config files. |
| configBackups | The host can manually trigger a backup of only config files. |
| saveBackups | The host can manually trigger a backup of only save data. |
| launchOptions | The host can both read and update server launch options, if the game supports them. |
The User Object
If a user object is included, the name key will be displayed alongside the connection on the Beacon website and in the app.
The id value is a string containing an identifying value of any kind. It will not be visible to the user. It could be a UUID, a number, or even an email address. However, for privacy reasons, it is probably best not to use an email address. Beacon will use this value to generate the stored token’s UUID.
By default, Beacon combines the Beacon account UUID, the discovery endpoint and the authentication token to generate a v5 UUID. This means that if a user deletes a connection from their account and adds the same authentication token again, the same UUID will be used and their projects will be able to find the connection. However, if the connection needs to be replaced for any reason, such as expiration or compromise, the UUID generated by Beacon will be different, and the user will need to re-import their servers to their projects.
To make this easier for users, Beacon will generate a UUID from the id value instead of the authentication token if a user object is available. This means that if a connection is replaced, the same UUID will be generated, and the user won’t need to update their projects. Consequently, the user can only have one connection per host. In most cases, this is okay. However, if this does not work for your implementation, include a differentiator with the id value of the user object. For example, you could append the token creation time to the end of the user’s ID, or set the value to a hash of the authentication token. This will effectively return Beacon to the behavior described in the previous paragraph.
UUID Generation Pseudocode
| Without User | v5_uuid(BeaconAccountID + DiscoveryURL + AccessToken) |
| With User | v5_uuid(BeaconAccountID + DiscoveryURL + UserID) |
Example Exchange
This exchange assumes the discovery endpoint given to the user is https://api.example.com/discovery.
Request
GET /discovery HTTP/1.1
Authorization: KEY secretToken
HOST: api.example.com
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"baseUrl": "https://api.example.com/v1",
"capabilities": [
"status",
"restarts",
"stopMessages",
"fullBackups",
"configBackups",
"saveBackups",
"launchOptions"
]
}
Endpoint Map
These are the other endpoints the Beacon Open Hosting API will look for. The baseUrl value returned by the discovery endpoint will be prepended to each of the below paths. For example, if baseUrl equals https://api.example.com/v1, a request to list servers would be made to https://api.example.com/v1/servers.
| Purpose | Endpoint |
|---|---|
| List Servers | GET /servers |
| Get Server Details | GET /servers/{serverId} |
| List Files | GET /servers/{serverId}/files |
| Download a File | GET /servers/{serverId}/files/{filePath} |
| Upload a File | PUT /servers/{serverId}/files/{filePath} |
| Start a Server | POST /servers/{serverId}/start |
| Stop a Server | POST /servers/{serverId}/stop |
| Get Launch Options | GET /servers/{serverId}/launchOptions |
| Set Launch Options | PUT /servers/{serverId}/launchOptions |
| Start a Backup | POST /servers/{serverId}/backup |
| Get Backup Status | GET /backups/{backupId} |
License
See License.