The extensive permissions system allows you to configure which data can be accessed by whom.
The main permissions file is located in the config/webapi folder and called permissions.conf.
Some additional permissions related to hooks are located in the hooks.conf file. This documentation
focuses mostly on the permissions.conf file, but the most of the things also apply to the
hooks.conf file.
Most of the permissions.conf file contains comments to explain what each part of the config does.
# Set this to true to enable the whitelist, false to turn it off
useWhitelist = true
# Add IP address that are allowed to connect to the Web-API to this list
whitelist = [
"127.0.0.1"
]The whitelist defines a basic IP-based restriction on who may access the Web-API. This setting is enabled by default, and set only to allow the localhost to connect.
If you wish to access the Web-API from another server than the one that your minecraft server is running on, you will have to add that IP here, or turn off whitelisting.
Turning off the whitelist is not recommended, unless you have properly set up permissions
# Set this to true to enable the blacklist, false to turn it off
useBlacklist = false
# Add the IP addresses that are NOT allowed to connect to the Web-API to this list
blacklist = [
"0.0.0.0"
]The blacklist controls which hosts are NOT allowed to access the Web-API. Use this to block out possible hosts spamming your server with requests.
# These are the default permissions that a client without a key receives
default {
# The permissions define which endpoints a user with this key can access, and what data is
# returned for each endpoint
permissions = {
info = "*"
player = {
one = {
"*" = true
uuid = false
}
}
}
# The rate limit specifies how many operations per second a client with this key can execute
rateLimit = 10
}These permissions are the ones that a client which doesn't specify a key receives. These permissions should generally be really restrictive, as anyone who can access the Web-API can access this data.
The rateLimit node specifies how many operations per second a client can execute.
The permissions node is a PermissionsTree, which is explained down below and specifies which
endpoints and what data from those endpoints a client can access.
# This is a map of keys, defining which keys give access to which endpoints.
keys {
# General usage
secretkey {
permissions {
info="*"
player {
one {
"*"=true
uuid=false
}
}
}
rateLimit = 0
}
# Example
# Use something secure and randomly generated for your key. (e.g. strongpasswordgenerator.com)
# Web-API will reject keys that are not at least 8 characters long
7S%M2FYp9NYT^Ozg {
# The "*" stands for all permissions and data
permissions="*"
# No rate limit or zero = unlimited requests
rateLimit=0
}
}The keys array is an array of permission structures similar to the ones explained above. The
only difference is that they have a key attribute, which is the key that the client needs
to pass in order to gain access to this set of permissions.
The key should generally be something secure and long enough to make it unfeasable to guess. The suggested way to go about this is to generate an arbitrary hash or password of at least 16 characters length
The client then has two ways to pass this key when accessing the Web-API:
- Set the
x-webapi-keyheader in the request - Set the
keyquery parameter in the request
The permissions properties above as well as the permissions properties listed in the
hooks.conf file use what is here referred to as a PermissionsTree. The tree defines
which endpoints of the API can be accessed and what data is returned for those endpoints.
permissions = {
info = "*"
player = {
one = {
"*" = true
uuid = false
}
}
}The two first levels of the permissions tree refer to the method of the Web-API (except when
using a PermissionsTree for the hooks.conf file. In that case you must leave those away).
So in this case info refers to the Info endpoint, which provides general information about
the minecraft server. Since this node is set to *, which is the allow all permission,
all the data for that endpoint will be returned.
The player node refers to the Player endpoint, which provides information about players
(when sending GET requests), and allows executing methods on the player object (when sending
POST requests).
Since the player.post permission node is not set, it is not allowed, and sending POST
requests to this endpoint will yield a 403 - Not allowed error.
The player.one permission is allowed, meaning that accessing the endpoint which returns one
player will return data. Which data is specified through the one node. The * node means
that all data is allowed, but more specific permissions always override the * node. So
in this case, all data except the uuid will be returned.
The key is a string specifying the name of the node. Following keys have special meaning:
| Key | Description |
|---|---|
| . | Refers to this permission |
| * | Referes to this and all sub permissions |
Each node can have any one of following values:
truefalse*- An object mapping keys to permission nodes
info = trueKey: info
Value: true
Allows access to the info node. Does not allow access to any sub nodes.
info = "*"Key: info
Value: *
This node allows full access to the info node and all sub nodes.
info = falseKey: info
Value: false
Denies access to the info node and all sub nodes.
player {
one {
"*" = true
uuid = false
location {
y = false
}
}
list {
"*" = false
uuid = true
link = true
}
change {
"." = false
}
}Key: player
Value: An object mapping keys to permission nodes
Allows full access to the player.one path, except for the uuid path and
the location.y path.
Allows access to the list endpoint, but returning only the uuid and link field.
Denies access to the player.change path. This could also be written as: change = false