RKing Industries
Developers

Sign in with RKING Industries

Let people log in to your website or app with their RKING Industries account and, if they allow it, let your app use their Minecraft servers through the API.

It's standard OAuth 2.0 (authorization code flow, with PKCE), so any OAuth library works: Passport, Auth.js / NextAuth, Authlib, AppAuth for iOS and Android, and so on. Your app never sees anyone's password.

Overview

1. Your appsends the person to our sign-in page
/oauth/authorize
2. They log in hereand see exactly what your app wants, then press Allow
3. We send them backto your redirect URI with a one-time code
4. Your appswaps the code for tokens and calls the API
/oauth/token
WhatURL
Sign-in page (authorization endpoint)https://rkingindustries.com/oauth/authorize
Token endpointhttps://rkingindustries.com/oauth/token
Who's signed in (userinfo)https://rkingindustries.com/oauth/userinfo or https://rkingindustries.com/api/v1/me
Sign out / revokehttps://rkingindustries.com/oauth/revoke
Server metadata (RFC 8414)https://rkingindustries.com/.well-known/oauth-authorization-server
Issuerhttps://rkingindustries.com

Access tokens last 60 minutes. Refresh tokens last 90 days and are replaced every time you use one. This is OAuth 2.0, not full OpenID Connect: there's no id_token, so call the userinfo endpoint to find out who signed in.

1. Register your app

Go to Your apps (you need an RKING Industries account) and press Register an app. Pick a type:

  • Has a server: a website, Discord bot or anything whose code runs on a server you control. You get a client ID and a client secret. Keep the secret on your server and never put it in a web page or mobile app.
  • Runs on people's devices: a phone, desktop or browser-only app. It can't keep a secret, so it gets a client ID only and must use PKCE.

Redirect URIs are where we send people back after they press Allow. They must match exactly what your app sends, character for character. Allowed forms:

  • https://yoursite.com/auth/rking/callback: any https address.
  • http://localhost:3000/callback or http://127.0.0.1/callback: for testing. On these, any port is accepted, so desktop apps can listen on a free port.
  • com.yourcompany.app:/callback: your phone or desktop app's own reverse-domain scheme.

A new app can ask for profile and email straight away. To use people's servers, tick the scopes you need when you register. RKING Industries reviews them, and you'll see them move from "waiting for review" to "can ask for" on your app's page.

2. Send people to sign in

Send the person's browser to the sign-in page with these query parameters. In a phone app, open it in the system browser (ASWebAuthenticationSession / Custom Tabs), not a web view.

ParameterWhat to send
response_typerequiredcode
client_idrequiredYour app's client ID, like rkapp_3f9a…
redirect_urirequiredOne of your registered redirect URIs. You can leave it out if you only registered one.
scopeoptionalSpace-separated scopes, like profile email servers:read. Defaults to profile, which is always included.
statestrongly recommendedA random value you make up for each sign-in and store (in a cookie or session). We send it back unchanged; check it matches. This stops attackers from logging people into the wrong account.
code_challengerequired for device appsThe PKCE challenge, see PKCE. Recommended for every app.
code_challenge_methodwith code_challengeS256 (the only one supported)
promptoptionalconsent always shows the Allow screen. none never shows a page: you get login_required or consent_required back if one would be needed.
https://rkingindustries.com/oauth/authorize?response_type=code
  &client_id=rkapp_3f9a1c0d2e4b6a8c9d0e
  &redirect_uri=https%3A%2F%2Fyoursite.com%2Fauth%2Frking%2Fcallback
  &scope=profile%20email%20servers%3Aread
  &state=Zk2pQ8vY1xR7
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

If the person has already allowed your app those scopes, they're sent straight back without seeing the Allow screen again.

3. Get the code back

When they press Allow, we redirect to your redirect URI:

https://yoursite.com/auth/rking/callback?code=rkc_Vh3…&state=Zk2pQ8vY1xR7&iss=https%3A//rkingindustries.com

Check that state matches what you stored. The code works once and only for 10 minutes. If something went wrong, or they pressed Cancel, you get an error instead:

https://yoursite.com/auth/rking/callback?error=access_denied&error_description=The+person+said+no&state=Zk2pQ8vY1xR7

Possible errors: access_denied (they pressed Cancel, or your app is switched off), invalid_scope (a scope is unknown or not approved for your app yet), invalid_request (usually PKCE is missing or malformed), unsupported_response_type, login_required and consent_required (only with prompt=none). If the client_id or redirect_uri is wrong, we can't safely send the person back, so they see an error page on our site instead.

4. Swap the code for tokens

From your server (or your device app, with PKCE), POST a form to the token endpoint. Apps with a secret send it with HTTP Basic auth (client_id:client_secret), or as client_id and client_secret form fields. Device apps send only client_id.

curl -X POST https://rkingindustries.com/oauth/token \
  -u "rkapp_3f9a1c0d2e4b6a8c9d0e:rks_YOUR_SECRET" \
  -d grant_type=authorization_code \
  -d code=rkc_Vh3... \
  -d redirect_uri=https://yoursite.com/auth/rking/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
{
  "access_token": "rka_9mQ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rkr_Lw2...",
  "scope": "profile email servers:read"
}

The scope in the reply is what you actually got. Store the refresh token securely (encrypted, on your server or in the device's keychain), never in a URL or log.

5. Call the API

Send the access token in the Authorization header on every request:

curl https://rkingindustries.com/api/v1/me -H "Authorization: Bearer rka_9mQ..."
{
  "id": 1234,
  "sub": "1234",
  "username": "steve",
  "created_at": "2026-03-02T18:21:09+00:00",
  "email": "[email protected]",
  "email_verified": true
}

Use id (or sub, the same number as a string) to recognise the person. Usernames can change. email and email_verified only appear with the email scope. /oauth/userinfo returns the same thing.

Refreshing tokens

Access tokens expire after 60 minutes (you'll get a 401 with invalid_token). Get a new one with the refresh token:

curl -X POST https://rkingindustries.com/oauth/token \
  -u "rkapp_3f9a1c0d2e4b6a8c9d0e:rks_YOUR_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=rkr_Lw2...

You get a new access token and a new refresh token. Save the new refresh token, because the old one stops working. If an old refresh token is ever used again, we assume it was stolen and sign your app out of that account completely; the person has to sign in again. You can add scope to ask for fewer scopes than before, never more.

Refreshing also fails with invalid_grant when the person has disconnected your app from their account page, or after 90 days without a refresh. Send them through sign-in again.

Signing out

When someone signs out of your app, revoke their tokens (RFC 7009). Revoking either token revokes both:

curl -X POST https://rkingindustries.com/oauth/revoke \
  -u "rkapp_3f9a1c0d2e4b6a8c9d0e:rks_YOUR_SECRET" \
  -d token=rkr_Lw2...

People can also see and disconnect your app any time from their account page.

PKCE

PKCE proves that the app swapping the code is the one that started the sign-in. It's required for apps without a secret and recommended for all. Before each sign-in:

  1. Make a code_verifier: 43-128 random characters from A-Z a-z 0-9 - . _ ~. Keep it until step 4.
  2. Make the code_challenge: base64url (no = padding) of the SHA-256 of the verifier. Send it with code_challenge_method=S256.
  3. Send the original code_verifier to the token endpoint.
// browser or Node 18+
function b64url(bytes) {
  return btoa(String.fromCharCode(...new Uint8Array(bytes)))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));

Scopes

Ask only for what you need: people are more likely to press Allow. They see the description on the Allow screen. Scopes marked "needs review" have to be approved for your app first.

ScopeWhat the person is told
profileSee your username and account IDevery app
emailSee your email addressevery app
servers:readSee your Minecraft servers: names, addresses, status, players, add-ons and statsneeds review
servers:controlStart, stop and restart your Minecraft serversneeds review makes changes
servers:consoleRead your servers' consoles and run commands on themneeds review makes changes
servers:filesSee, change, upload and delete files on your servers, and make, restore and delete backupsneeds review makes changes
servers:manageChange your servers' settings: name, address, version, add-ons, modpacks, permissions, appearance, voting and public pageneeds review makes changes

profile is always included. Apps can never touch billing, buy or delete servers, reset a server, or change someone's account, whatever scopes they have.

API reference

All endpoints are under https://rkingindustries.com, take Authorization: Bearer <access token>, and return JSON. Request bodies are JSON (Content-Type: application/json), except file uploads, which are multipart/form-data. You can only reach the person's own servers. Failures look like {"ok": false, "error": "a message you can show the person"}.

The most useful ones

RequestWhat it does
GET /api/v1/meWho's signed in (see above).
GET /api/minecraft/serversTheir servers: a list of objects with id, name, software, version, domain (the address players join), java_port, bedrock_port, state (online, starting, offline…), plan, plan_name, expires_at, asleep and more.
GET /api/minecraft/servers/{id}One server, same fields.
GET /api/minecraft/servers/{id}/statsLive numbers: state, players_online, players_max, player_names, tps, cpu_percent, mem_used_mb, disk_bytes, uptime_seconds.
POST /api/minecraft/servers/{id}/start
…/stop · …/restart
No body. Returns {"ok": true}. Can fail with 402 (plan expired) or 507 (out of storage).
GET /api/minecraft/servers/{id}/logs{"logs": "…"}: the last 300 console lines.
POST /api/minecraft/servers/{id}/commandBody {"command": "say hello"} (no slash, up to 300 characters). The server must be online. Returns {"ok": true, "output": "…"}.
GET /api/minecraft/servers/{id}/files?path=pluginsThe files in a folder.
GET /api/minecraft/servers/{id}/files/read?path=server.propertiesA text file's contents (up to 1 MB). files/download streams any file.
POST /api/minecraft/servers/{id}/files/writeBody {"path": "server.properties", "content": "…"}.
POST /api/minecraft/servers/{id}/files/mkdir · files/deleteBody {"path": "…"}.
POST /api/minecraft/servers/{id}/files/upload?path=pluginsMultipart, one or more files fields.
GET /api/minecraft/servers/{id}/backupsIts backups. POST to the same URL to make one now. backups/restore and backups/delete take {"name": "…"}.
POST /api/minecraft/servers/{id}/settings/nameBody {"name": "My SMP"}.

Everything apps can call

These are the same endpoints the server panel on rkingindustries.com uses. Anything not listed refuses app tokens with 403. If you need the details of one that isn't described above, ask us.

RequestScope needed
GET /api/v1/meprofile
GET /api/minecraft/serversservers:read
GET /api/minecraft/servers/{id}servers:read
GET /api/minecraft/servers/{id}/statsservers:read
GET /api/minecraft/servers/{id}/stats/historyservers:read
GET /api/minecraft/servers/{id}/addonsservers:read
GET /api/minecraft/servers/{id}/access/listsservers:read
GET /api/minecraft/servers/{id}/appearanceservers:read
GET /api/minecraft/servers/{id}/appearance/icon.pngservers:read
GET /api/minecraft/servers/{id}/votesservers:read
GET /api/minecraft/servers/{id}/public/pageservers:read
POST /api/minecraft/servers/{id}/start|stop|restartservers:control
GET /api/minecraft/servers/{id}/logsservers:console
POST /api/minecraft/servers/{id}/commandservers:console
GET /api/minecraft/servers/{id}/filesservers:files
GET /api/minecraft/servers/{id}/files/readservers:files
GET /api/minecraft/servers/{id}/files/downloadservers:files
POST /api/minecraft/servers/{id}/files/writeservers:files
POST /api/minecraft/servers/{id}/files/uploadservers:files
POST /api/minecraft/servers/{id}/files/mkdirservers:files
POST /api/minecraft/servers/{id}/files/deleteservers:files
GET /api/minecraft/servers/{id}/backupsservers:files
POST /api/minecraft/servers/{id}/backupsservers:files
POST /api/minecraft/servers/{id}/backups/settingsservers:files
POST /api/minecraft/servers/{id}/backups/restoreservers:files
POST /api/minecraft/servers/{id}/backups/deleteservers:files
POST /api/minecraft/servers/{id}/settings/nameservers:manage
POST /api/minecraft/servers/{id}/settings/addressservers:manage
POST /api/minecraft/servers/{id}/versionservers:manage
POST /api/minecraft/servers/{id}/problem/fixservers:manage
POST /api/minecraft/servers/{id}/appearance/motdservers:manage
POST /api/minecraft/servers/{id}/appearance/iconservers:manage
POST /api/minecraft/servers/{id}/appearance/icon/removeservers:manage
POST /api/minecraft/servers/{id}/access/listsservers:manage
GET /api/minecraft/servers/{id}/luckperms/stateservers:manage
POST /api/minecraft/servers/{id}/luckperms/runservers:manage
GET /api/minecraft/servers/{id}/addons/searchservers:manage
POST /api/minecraft/servers/{id}/addons/installservers:manage
POST /api/minecraft/servers/{id}/addons/updateservers:manage
POST /api/minecraft/servers/{id}/addons/removeservers:manage
GET /api/minecraft/modpacksservers:manage
GET /api/minecraft/modpacks/{project}/versionsservers:manage
GET /api/minecraft/modpacks/{project}/versions/{version_id}/needsservers:manage
POST /api/minecraft/servers/{id}/modpack/installservers:manage
POST /api/minecraft/servers/{id}/modpack/retryservers:manage
POST /api/minecraft/servers/{id}/modpack/missing/clearservers:manage
POST /api/minecraft/servers/{id}/public/pageservers:manage
POST /api/minecraft/servers/{id}/votes/settingsservers:manage
POST /api/minecraft/servers/{id}/votes/testservers:manage

Errors

StatusMeansWhat to do
401 invalid_tokenThe access token is wrong, expired or revoked, the person's account can't be used, or your app has been switched off.Refresh the token. If that fails, sign them in again.
403 insufficient_scopeThe token doesn't have the scope this needs (the WWW-Authenticate header names it), or apps can't use this endpoint at all.Sign them in again asking for that scope, if your app is approved for it.
404No such server, or it isn't theirs.
429Too many requests.Wait for the Retry-After seconds.
400 / 402 / 507The action isn't possible right now (e.g. server offline, plan expired, out of storage).Show the person the error message.

The token endpoint uses the standard OAuth errors: invalid_client (wrong client ID or secret, 401), invalid_grant (code or refresh token is wrong, used, expired or revoked), invalid_scope, unsupported_grant_type and slow_down (429).

Limits

  • 300 API requests a minute per access token.
  • 30 failed token requests per 15 minutes per IP address, then the token endpoint refuses that address for a while.
  • Up to 10 apps per account and 10 redirect URIs per app.
  • Browser apps can call the token endpoint and the API directly (CORS is open for requests with a bearer token, without cookies).

Rules

Never ask people for their RKING Industries password. Always send them to our sign-in page, and in apps open it in the real browser so they can see the address bar. Apps that collect passwords are switched off.
  • Keep the client secret on your server. If it leaks, make a new one on Your apps straight away: the old one stops working at once.
  • Always use and check state, and use PKCE.
  • Only do what the person would expect from what they allowed. Don't run commands or change files they didn't ask for.
  • Don't call your app anything with "RKING" in it or make it look like ours.
  • RKING Industries can take scopes away from, or switch off, any app at any time. Using the API also means following our terms.

Examples

Node.js (Express), a website with a server

// npm install express express-session
import express from "express";
import session from "express-session";
import crypto from "node:crypto";

const RK = "https://rkingindustries.com";
const CLIENT_ID = process.env.RK_CLIENT_ID;
const CLIENT_SECRET = process.env.RK_CLIENT_SECRET;     // keep it out of your code
const REDIRECT_URI = "http://localhost:3000/auth/rking/callback";

const app = express();
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));
const b64url = buf => buf.toString("base64url");

app.get("/login", (req, res) => {
  req.session.state = b64url(crypto.randomBytes(16));
  req.session.verifier = b64url(crypto.randomBytes(32));
  const challenge = b64url(crypto.createHash("sha256").update(req.session.verifier).digest());
  const url = new URL(RK + "/oauth/authorize");
  url.search = new URLSearchParams({
    response_type: "code", client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
    scope: "profile email", state: req.session.state,
    code_challenge: challenge, code_challenge_method: "S256",
  });
  res.redirect(url.toString());
});

app.get("/auth/rking/callback", async (req, res) => {
  if (!req.query.state || req.query.state !== req.session.state) return res.status(400).send("Bad state");
  if (req.query.error) return res.send("Sign-in cancelled: " + req.query.error);
  const r = await fetch(RK + "/oauth/token", {
    method: "POST",
    headers: { Authorization: "Basic " + Buffer.from(CLIENT_ID + ":" + CLIENT_SECRET).toString("base64") },
    body: new URLSearchParams({
      grant_type: "authorization_code", code: req.query.code,
      redirect_uri: REDIRECT_URI, code_verifier: req.session.verifier,
    }),
  });
  const tokens = await r.json();
  if (!r.ok) return res.status(400).send(tokens.error_description);
  const me = await (await fetch(RK + "/api/v1/me", { headers: { Authorization: "Bearer " + tokens.access_token } })).json();
  req.session.user = { id: me.id, username: me.username, email: me.email };   // your own login from here on
  req.session.refresh = tokens.refresh_token;
  res.redirect("/");
});

app.listen(3000);

Python (requests), calling the API

import requests

RK = "https://rkingindustries.com"
AUTH = ("rkapp_3f9a1c0d2e4b6a8c9d0e", "rks_YOUR_SECRET")

def refresh(refresh_token):
    r = requests.post(RK + "/oauth/token", auth=AUTH,
                      data={"grant_type": "refresh_token", "refresh_token": refresh_token})
    r.raise_for_status()
    return r.json()          # save BOTH new tokens: the old refresh token no longer works

def api(token, method, path, **kw):
    r = requests.request(method, RK + path, headers={"Authorization": f"Bearer {token}"}, **kw)
    if r.status_code == 401:
        raise PermissionError("Token expired: refresh it")
    return r.json()

servers = api(token, "GET", "/api/minecraft/servers")
for s in servers:
    print(s["name"], s["domain"], s["state"])
api(token, "POST", f"/api/minecraft/servers/{servers[0]['id']}/restart")

Using a library

Most OAuth libraries only need these settings:

authorization URL:  https://rkingindustries.com/oauth/authorize
token URL:          https://rkingindustries.com/oauth/token
userinfo URL:       https://rkingindustries.com/oauth/userinfo
scopes:             profile email
PKCE:               S256
client auth:        client_secret_basic (or "none" for device apps)
user id field:      id   (username: username, email: email)

Questions, or need a scope we don't have? Get in touch.