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
/oauth/authorize
code/oauth/token
| What | URL |
|---|---|
| Sign-in page (authorization endpoint) | https://rkingindustries.com/oauth/authorize |
| Token endpoint | https://rkingindustries.com/oauth/token |
| Who's signed in (userinfo) | https://rkingindustries.com/oauth/userinfo or https://rkingindustries.com/api/v1/me |
| Sign out / revoke | https://rkingindustries.com/oauth/revoke |
| Server metadata (RFC 8414) | https://rkingindustries.com/.well-known/oauth-authorization-server |
| Issuer | https://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/callbackorhttp://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.
| Parameter | What to send | |
|---|---|---|
response_type | required | code |
client_id | required | Your app's client ID, like rkapp_3f9a… |
redirect_uri | required | One of your registered redirect URIs. You can leave it out if you only registered one. |
scope | optional | Space-separated scopes, like profile email servers:read. Defaults to profile, which is always included. |
state | strongly recommended | A 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_challenge | required for device apps | The PKCE challenge, see PKCE. Recommended for every app. |
code_challenge_method | with code_challenge | S256 (the only one supported) |
prompt | optional | consent 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:
- Make a
code_verifier: 43-128 random characters fromA-Z a-z 0-9 - . _ ~. Keep it until step 4. - Make the
code_challenge: base64url (no=padding) of the SHA-256 of the verifier. Send it withcode_challenge_method=S256. - Send the original
code_verifierto 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.
| Scope | What the person is told | |
|---|---|---|
profile | See your username and account ID | every app |
email | See your email address | every app |
servers:read | See your Minecraft servers: names, addresses, status, players, add-ons and stats | needs review |
servers:control | Start, stop and restart your Minecraft servers | needs review makes changes |
servers:console | Read your servers' consoles and run commands on them | needs review makes changes |
servers:files | See, change, upload and delete files on your servers, and make, restore and delete backups | needs review makes changes |
servers:manage | Change your servers' settings: name, address, version, add-ons, modpacks, permissions, appearance, voting and public page | needs 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
| Request | What it does |
|---|---|
GET /api/v1/me | Who's signed in (see above). |
GET /api/minecraft/servers | Their 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}/stats | Live 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}/command | Body {"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=plugins | The files in a folder. |
GET /api/minecraft/servers/{id}/files/read?path=server.properties | A text file's contents (up to 1 MB). files/download streams any file. |
POST /api/minecraft/servers/{id}/files/write | Body {"path": "server.properties", "content": "…"}. |
POST /api/minecraft/servers/{id}/files/mkdir · files/delete | Body {"path": "…"}. |
POST /api/minecraft/servers/{id}/files/upload?path=plugins | Multipart, one or more files fields. |
GET /api/minecraft/servers/{id}/backups | Its backups. POST to the same URL to make one now. backups/restore and backups/delete take {"name": "…"}. |
POST /api/minecraft/servers/{id}/settings/name | Body {"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.
| Request | Scope needed |
|---|---|
GET /api/v1/me | profile |
GET /api/minecraft/servers | servers:read |
GET /api/minecraft/servers/{id} | servers:read |
GET /api/minecraft/servers/{id}/stats | servers:read |
GET /api/minecraft/servers/{id}/stats/history | servers:read |
GET /api/minecraft/servers/{id}/addons | servers:read |
GET /api/minecraft/servers/{id}/access/lists | servers:read |
GET /api/minecraft/servers/{id}/appearance | servers:read |
GET /api/minecraft/servers/{id}/appearance/icon.png | servers:read |
GET /api/minecraft/servers/{id}/votes | servers:read |
GET /api/minecraft/servers/{id}/public/page | servers:read |
POST /api/minecraft/servers/{id}/start|stop|restart | servers:control |
GET /api/minecraft/servers/{id}/logs | servers:console |
POST /api/minecraft/servers/{id}/command | servers:console |
GET /api/minecraft/servers/{id}/files | servers:files |
GET /api/minecraft/servers/{id}/files/read | servers:files |
GET /api/minecraft/servers/{id}/files/download | servers:files |
POST /api/minecraft/servers/{id}/files/write | servers:files |
POST /api/minecraft/servers/{id}/files/upload | servers:files |
POST /api/minecraft/servers/{id}/files/mkdir | servers:files |
POST /api/minecraft/servers/{id}/files/delete | servers:files |
GET /api/minecraft/servers/{id}/backups | servers:files |
POST /api/minecraft/servers/{id}/backups | servers:files |
POST /api/minecraft/servers/{id}/backups/settings | servers:files |
POST /api/minecraft/servers/{id}/backups/restore | servers:files |
POST /api/minecraft/servers/{id}/backups/delete | servers:files |
POST /api/minecraft/servers/{id}/settings/name | servers:manage |
POST /api/minecraft/servers/{id}/settings/address | servers:manage |
POST /api/minecraft/servers/{id}/version | servers:manage |
POST /api/minecraft/servers/{id}/problem/fix | servers:manage |
POST /api/minecraft/servers/{id}/appearance/motd | servers:manage |
POST /api/minecraft/servers/{id}/appearance/icon | servers:manage |
POST /api/minecraft/servers/{id}/appearance/icon/remove | servers:manage |
POST /api/minecraft/servers/{id}/access/lists | servers:manage |
GET /api/minecraft/servers/{id}/luckperms/state | servers:manage |
POST /api/minecraft/servers/{id}/luckperms/run | servers:manage |
GET /api/minecraft/servers/{id}/addons/search | servers:manage |
POST /api/minecraft/servers/{id}/addons/install | servers:manage |
POST /api/minecraft/servers/{id}/addons/update | servers:manage |
POST /api/minecraft/servers/{id}/addons/remove | servers:manage |
GET /api/minecraft/modpacks | servers:manage |
GET /api/minecraft/modpacks/{project}/versions | servers:manage |
GET /api/minecraft/modpacks/{project}/versions/{version_id}/needs | servers:manage |
POST /api/minecraft/servers/{id}/modpack/install | servers:manage |
POST /api/minecraft/servers/{id}/modpack/retry | servers:manage |
POST /api/minecraft/servers/{id}/modpack/missing/clear | servers:manage |
POST /api/minecraft/servers/{id}/public/page | servers:manage |
POST /api/minecraft/servers/{id}/votes/settings | servers:manage |
POST /api/minecraft/servers/{id}/votes/test | servers:manage |
Errors
| Status | Means | What to do |
|---|---|---|
401 invalid_token | The 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_scope | The 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. |
404 | No such server, or it isn't theirs. | |
429 | Too many requests. | Wait for the Retry-After seconds. |
400 / 402 / 507 | The 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
- 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.