https://github.com/luckperms/rest-api
A REST API for LuckPerms.
https://github.com/luckperms/rest-api
Last synced: about 1 year ago
JSON representation
A REST API for LuckPerms.
- Host: GitHub
- URL: https://github.com/luckperms/rest-api
- Owner: LuckPerms
- License: mit
- Created: 2022-07-23T00:56:44.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-05T18:57:46.000Z (almost 2 years ago)
- Last Synced: 2025-03-23T06:11:53.014Z (about 1 year ago)
- Language: Java
- Size: 196 KB
- Stars: 32
- Watchers: 1
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# luckperms-rest-api
A REST API for LuckPerms.
* [API Specification](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/LuckPerms/rest-api/main/src/main/resources/luckperms-openapi.yml)
## Information
* The REST API is bundled as a LuckPerms "[extension](https://luckperms.net/wiki/Extensions)".
* We suggest that you run the rest-api as a standalone application within a Docker container. (see below)
* The API is still a work in progress. Please submit bugs/suggestions in the issues section!
## Usage (Docker)
1. Copy the example [docker-compose.yml](docker/docker-compose.yml) file to somewhere sensible.
2. Open the file and configure your database host/credentials
3. Run `docker compose up -d`
4. The API is now accessible (by default) at `http://127.0.0.1:8080`.
## Usage (Manual)
1. Clone the repository
2. Compile with Gradle (`./gradlew build`)
3. Add `luckperms-rest-api-v1.jar` to the LuckPerms extension folder (`/data/extensions/`).
4. The API is now accessible (by default) at `http://localhost:8080`.
## Configuration
The app can be configured using Java system properties or environment variables.
| Environment Variable | Description | Default Value |
|-------------------------------|----------------------------------------------------------------|---------------|
| `LUCKPERMS_REST_HTTP_PORT` | The port that the HTTP server should listen on | `8080` |
| `LUCKPERMS_REST_AUTH` | If API key authorization is enabled | `false` |
| `LUCKPERMS_REST_AUTH_KEYS` | A comma-separated list of accepted API keys | *none* |
| `LUCKPERMS_REST_CACHE_USERS` | If the cache* should be used for user GET requests | `true` |
| `LUCKPERMS_REST_CACHE_GROUPS` | If the cache* should be used for group GET requests | `true` |
***** When a [messaging service](https://luckperms.net/wiki/Syncing-data-between-servers#messaging-services) is configured (recommended), the cache will be invalidated automatically whenever data is changed by other LP instances.
## Security
By default, the example Docker Compose setup only makes the API available to applications running on the host machine.
For this reason, authentication is disabled by default.
However, if you decide to make the API available over a wider network (e.g. the internet), then it is crucial that **you configure authentication using API keys** and enable HTTPS by exposing the API behind a reverse proxy (e.g. nginx).
You enable auth by setting `LUCKPERMS_REST_AUTH` to true, and setting `LUCKPERMS_REST_AUTH_KEYS` to a comma separated list of allowed API keys.
e.g.
```yml
LUCKPERMS_REST_AUTH: "true"
LUCKPERMS_REST_AUTH_KEYS: "myverysecureapikey,anotherverysecurekey"
```
Once enabled, API keys should be sent as a `Bearer` token inside the `Authorization` header of API requests.
e.g.
```
Authorization: Bearer myverysecureapikey
```