Dungeon Hub API ✏️

What is the Dungeon Hub API

The Dungeon Hub API hosts all data that is used in the Dungeon Hub Bot.
The Dungeon Hub Bot itself only serves as a client to interact with the API - it does not have any database access and only persists data through the API. A documentation with all endpoints and their usage can be found at https://api.dungeon-hub.net/.

Authentication

Most endpoints of the Dungeon Hub API require authentication.
The API uses bearer tokens for authentication, meaning an Authorization header containing the JWT token must be attached to the request.
The header should look like: Authorization: Bearer <token>.
A token can be obtained from the authentication server, which is hosted separately to the API at https://auth.dungeon-hub.net/.

Logging in as a user

Coming soon

Logging in as a client

To log in as a client, you need to send a POST request to https://auth.dungeon-hub.net/realms/dungeon-hub/protocol/openid-connect/token.
The request body should be a multipart form containing the following fields:

client_id: dh-server
grant_type: client_credentials

As the Authorization header, you should use basic authentication with the client's credentials (client id as username, client secret as password).

Connecting to the API

All API endpoints are reachable under https://api.dungeon-hub.net/. A simple documentation of all endpoints is available there.
To ease the connection to the API, a Kotlin/JVM library containing all models that the API uses in requests and responses, as well as a library to send requests to all possible endpoints is available at https://github.com/dungeon-hub/dungeon-hub-api.

Importing the client library

First of all, add a dependency to your gradle/libs.versions.toml file.

This file is used to declare the versions of libraries you use in one central place.

                        [versions]
                        dungeon-hub-api-client = "0.5.7"

                        [libraries]
                        dungeon-hub-api-client = {module = "net.dungeon-hub.api:client", version.ref = "dungeon-hub-api-client" }
                    

Then, you can simply add the dependency to your build.gradle.kts file.

                        repositories {
                            // other repositories

                            mavenCentral()
                        }

                        dependencies {
                            // other dependencies

                            implementation(libs.dungeon.hub.api.client)
                        }
                    

First of all, add a dependency to your gradle/libs.versions.toml file.

This file is used to declare the versions of libraries you use in one central place.

                        [versions]
                        dungeon-hub-api-client = "0.5.7"

                        [libraries]
                        dungeon-hub-api-client = {module = "net.dungeon-hub.api:client", version.ref = "dungeon-hub-api-client" }
                    

Then, you can simply add the dependency to your build.gradle file.

                        repositories {
                            // other repositories

                            mavenCentral()
                        }

                        dependencies {
                            // other dependencies

                            implementation(libs.dungeon.hub.api.client)
                        }
                    

Please add the following to your `pom.xml`:

                        <dependencies>
                            <dependency>
                                <groupId>net.dungeon-hub.api</groupId>
                                <artifactId>client</artifactId>
                                <version>0.5.7</version>
                            </dependency>
                        </dependencies>
                    

Last modified: 27 February 2025