🔑 BetaKey – Advanced Beta Access System

Only players with a key can join your server. Create keys ingame, on Discord or in the web admin panel, and let players redeem them on your own website or with the Discord bot. One plugin for Spigot/Paper, BungeeCord and Velocity.

Features

Supported platforms

Minecraft 1.7 is not supported. On a BungeeCord/Velocity network, install BetaKey on the proxy.

Quick start

1. Put the BetaKey jar for your platform into the plugins folder and start the server.
2. BetaKey creates its files and uses SQLite, so it works right away:

   plugins/BetaKey/
     config.yml          settings (database, Discord bot, website, bypass list)
     messages/           ingame messages: en-us.yml, de-de.yml, your own languages
     database/BetaKey.db the keys (SQLite)
     website/            website settings, themes and texts

3. Create a key: /betakey create random
4. Let players redeem their keys, on the website (/betakey website enable) or with the Discord bot (/betakey discord enable).
5. Players with a redeemed key can join. Everyone else gets the kick message.

Guides

Commands and permissions

All /betakey commands need the permission betakey.admin (also available as /key and /betakeysystem). The console can always use them. Players use /link without a permission.

Languages

The ingame messages are in plugins/BetaKey/messages. Choose the language in the config.yml:

Language: auto          # language of each player's Minecraft client, or a file name like de-de
DefaultLanguage: en-us  # used if there is no file for the client language

To add a language, copy en-us.yml (e.g. to fr-fr.yml) and translate it. A file only needs the messages you want to change, everything else is taken from en-us.yml.

Updating from BetaKey 3.x

Replace the jar and start the server. BetaKey updates everything automatically:

• Your old config.yml is saved as config.yml.v1.backup (or the number of your old version).
• The new config.yml keeps all your settings and gets the new comments.
• Your messages are moved to messages/legacy-mig.yml, and the language is set to legacy-mig, so your server keeps its own texts. Set Language: auto to use the new translations instead.
• An SQLite database of BetaKey 3.x is copied to database/BetaKey.db. MySQL databases stay as they are.

Why BetaKey?

• 58+ customers
• 100% satisfaction rate
• Active development and support

"This is the best BETA KEY system plugin in the world !!!" – JackTailor

Support

Need help? Join our Discord server or ask in the forum. Please run /betakey debug and send us the output, it contains everything we need and no passwords.

BetaKey Website

BetaKey 4.0 comes with its own website. It runs directly inside the plugin on your Minecraft server or proxy, so you don't need a separate webserver, PHP or an extra database. Players redeem their keys on it, and admins manage all keys in the admin panel.

Features

• Redeem page: players enter their Minecraft name and their key. BetaKey checks the name with Mojang and stores the UUID.
• Admin panel on /admin: statistics, who uses which key, search, creating and deleting keys.
• Themes: change the design with your own templates and CSS, without changing the plugin.
• Languages: English and German included, the visitor's browser language is chosen automatically.
• Works with every database BetaKey supports: SQLite, MySQL, MariaDB and PostgreSQL.
• Protection: rate limits against guessing keys, salted and hashed admin passwords, optional ingame confirmation of admin logins.

Requirements

• BetaKey 4.0 or newer (Spigot/Paper 1.8.8+, BungeeCord or Velocity)
• A free TCP port for the website, 8080 by default. Your host must let you open it (firewall / port forwarding).

Quick start

1. Enable the website ingame or in the console:

   /betakey website enable

   This sets Website.Enabled: true in the config.yml and starts the website right away. You can also change it in the config.yml yourself and run /betakey reload.
2. Check that it is running:

   /betakey website

   This shows all website commands and the address, e.g. The website is running on http://<server-ip>:8080/.
3. Open http://<your-server-ip>:8080/ in your browser. You should see the redeem page.
4. Optional: set your server name, port and theme in plugins/BetaKey/website/settings.yml and run /betakey reload.

The website folder

plugins/BetaKey/website/
  settings.yml        port, address, theme, language, admin panel
  lang/en.yml         texts of the website
  lang/de.yml
  themes/default/     the default theme
  themes/dark/        example theme, only overrides a few files

Missing files are restored on startup, but existing files are never overwritten. To get the newest version of a file after an update, delete it and restart the server or run /betakey reload.

settings.yml

Run /betakey reload after changing the settings.

Admin panel

The admin panel is available on <website>/admin, e.g. http://<server-ip>:8080/admin. It shows how many keys exist, how many are used and unused, which player uses which key, and lets you search, create (1-100 random keys or a custom key) and delete keys. Every action is logged in the server console.

Login methods

Setting up an admin

1. Join the server with a player that has the permission betakey.admin and set your password:

   /betakey website password <password>

   The password needs 8 to 128 characters. It is stored salted and hashed in the database, and BetaKey hides this command from the server log.
2. Open /admin on the website and log in with your Minecraft name and the password.
3. With BOTH or INGAME the website now shows a code. Run it ingame with the same player:

   /betakey verify 123456

   Only the player who logs in can confirm the login, other admins can't. The page continues automatically.

To remove the access of an admin, run /betakey website removepassword <player>. This also logs out all sessions of that admin.

HTTPS with a reverse proxy

The website itself uses HTTP. Without HTTPS, admin passwords are sent unencrypted, and BetaKey warns about this in the console and on the login page. For a public website, put it behind a reverse proxy like nginx (with a Let's Encrypt certificate) or Cloudflare.

1. Let the website only listen locally: Host: 127.0.0.1
2. Set your address: PublicUrl: 'https://beta.yourserver.net/'
3. Set TrustProxyHeaders: true, so the rate limits use the real visitor IP.
4. Configure the proxy, for example nginx:

server {
    listen 443 ssl;
    server_name beta.yourserver.net;

    ssl_certificate     /etc/letsencrypt/live/beta.yourserver.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beta.yourserver.net/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        # set the visitor IP yourself, so visitors can't fake it
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header CF-Connecting-IP $remote_addr;
    }
}

Themes

A theme is a folder in website/themes. It only needs the files it changes, everything else is taken from its parent theme and finally from the default theme. Templates use Pebble.

themes/mytheme/
  theme.yml               Name, Author and Parent
  templates/layout.peb    page frame (blocks: title, head, header, content, footer)
  templates/redeem.peb    the redeem page
  templates/admin/        admin panel pages (login.peb, verify.peb, dashboard.peb)
  assets/                 css, images, ... available as /assets/<file>

Create your own theme

1. Create the folder website/themes/mytheme with a theme.yml:

   Name: My Theme
   Author: You
   Parent: default

2. Add assets/mytheme.css with your colors. The default theme uses CSS variables, so a few lines are enough:

   :root {
     --accent: #e67e22;
     --accent-hover: #d35400;
   }

3. Add templates/layout.peb, which extends the default layout and loads your CSS:

   {% extends "default:layout.peb" %}
   
   {% block head %}
     {{ parent() }}
     <link rel="stylesheet" href="/assets/mytheme.css">
   {% endblock %}

4. Set Theme: mytheme in the settings.yml and run /betakey reload.

Languages

The texts of the website are in website/lang, one file per language (en.yml, de.yml). The visitor's browser language is used automatically, and visitors can switch the language at the bottom of the page. To add a language, copy en.yml, e.g. to fr.yml, and translate it. Texts missing in a file are taken from the English file.

The ingame messages of BetaKey are in a separate folder, plugins/BetaKey/messages.

BungeeCord and Velocity networks

Enable the website on one BetaKey instance only, usually the proxy. If BetaKey runs on several servers, they all have to use the same MySQL, MariaDB or PostgreSQL database. SQLite only works for one server.

Commands

All commands need the permission betakey.admin. In the chat you can click a command in /betakey website to use it.

Troubleshooting

If you need help, run /betakey debug and send the output to the support. It contains no passwords, tokens or codes.

BetaKey Legacy Website

The legacy website is the PHP redeem page of older BetaKey versions. It runs on a separate webserver and connects to the same MySQL database as the plugin. It is still available, but it gets no new features.

When to use the legacy website

Only use the legacy website if the new website can't be used on your server, for example:

• Your host only gives you one port (the game port), so the new website can't be reached from the internet.
• You want the redeem page on your existing web hosting, and you can't run a reverse proxy to the Minecraft server.

If you can open a second port on your server, use the new website.

New website or legacy website?

Requirements

• A webserver with PHP 7.4 or newer and the pdo_mysql extension (most web hostings have both).
• BetaKey configured with mysql or mariadb. SQLite and PostgreSQL don't work with the legacy website.
• The webserver must be able to connect to the database (remote access to MySQL/MariaDB).

Setup

1. Switch BetaKey to MySQL or MariaDB. In plugins/BetaKey/config.yml:

   MySQL:
     DatabaseManagementSystem: "mysql"
     Host: your-database-host
     Port: 3306
     Database: Betasystem
     User: betakey
     Password: YourPassword

   Restart the server (or run /betakey reload), so BetaKey connects and creates its tables. /betakey debug shows whether the database is connected.
2. Create a database user for the website. The legacy website only reads and updates the keys, so give it only these rights and only from the address of your webserver:

   CREATE USER 'betakey_web'@'webserver-ip' IDENTIFIED BY 'a-strong-password';
   GRANT SELECT, UPDATE ON Betasystem.BetaKeys TO 'betakey_web'@'webserver-ip';

   Make sure your database (and its firewall) accepts connections from the webserver.
3. Upload the files. Upload the content of the legacy-website folder to your webserver, for example to public_html/beta:

   index.php       sends visitors to the German or English page
   MYSQL.php       database connection
   background.png
   de/             German page
   en/             English page

4. Enter the database connection in MYSQL.php. Use the same database as BetaKey:

   $Host = "your-database-host";
   $User = "betakey_web";
   $Database = "Betasystem";
   $Password = "a-strong-password";
   $Port = "3306";

5. Test it. Create a key with /betakey create random, open the website and redeem it. The player can join the server right away.

Security and privacy

Troubleshooting