Documentation

Everything, A to Z

The whole product on one page: the panel, the account flows, the API routes worth integrating against, the webhook contract and the Discord bot — plus the one SQL statement an admin needs.

01

What this is

Two halves that talk to one database. The panel is where an account owns applications, issues keys, watches sessions and controls who may use them. The SDK is two public endpoints a build calls at launch — nothing to install, no vendor binary, just JSON over HTTPS.

Panel

Account signup, 2FA, passkeys, applications, licence keys, sub-users, sessions, logs, blacklists, messages, webhooks, teammates and billing. Everything is server-rendered, so a page is always the truth.

SDK

POST /api/v1/verify for a key, POST /api/v1/login for one of your own users. Both take the app id and secret, return the owner's own copy strings, and can bind a machine on first contact.

Storage

Postgres holds accounts, keys, sessions and the audit trail. Pictures — avatars and app icons — live in object storage and are streamed back through the API under a content hash, never from a public bucket.

Discord bot

A hosted bot you invite to a server. `/login` with an account token turns it into a live read-only briefing: applications, keys, users, plan and security state.

02

Accounts and security

An account is one email, one username, one password hash. Four things can open it: the password, the account token, a passkey, or a second-factor code on top of the password. The account token is the deliberate exception — it replaces every factor, which is why it is masked, mailed once and rotated on demand.

Signup

Two calls. `start` validates the name and address and mails a six-digit code; `verify` creates the row, mints the account token, mails that too, and signs the session in. No password is stored in plain text — scrypt with the same parameters everywhere.

Sign-in

`/api/auth/login` answers with a session, or — when 2FA is on — a challenge. The second call carries `code`, which may be an authenticator code, a mailed code, or one of the ten backup codes. Backup codes are single-use; used rows stay behind so the panel can count what's left.

Account token

Shape `nct_` plus 32 URL-safe characters. Created on first read after signup and mailed. `/api/auth/token` trades it for a session with no password and no second factor; the Discord bot trades it for a briefing. Rotating it in Settings mails the new one and kills every holder of the old.

2FA wizard

Password, then Verify, then Send code, then the mailed code, then the authenticator code — Done collapses the card. Backup codes are generated behind the same password and downloadable once as a text file. Disabling takes the password again.

Passkeys

WebAuthn enrolment and assertion. The challenge lives in the database and only its id travels in a cookie, so options cannot be replayed. If the account also holds a TOTP seed, the passkey alone is not enough.

Deletion

Type the username, type the password, hold the button. With 2FA on, the authenticator code is a third proof. Everything must match before a single row is removed, and the session is cleared after.

03

The panel

One account, many applications, one selected at a time. The selection lives in a cookie so the server can render the right rows on the first paint instead of flashing the wrong app.

Dashboard

Totals across every project, the plan strip, and one merged activity timeline with a 14-day chart.

Projects

Every application with its size. The create button answers the plan ceiling before it opens a form.

Licences

Bulk generation from a mask, status, bound HWID, expiry, last seen, and a reset action per key.

Users

Sub-users your own login screen authenticates. Password reset, HWID reset, expiry, ban.

Sessions

Live sessions from both SDK doors, closeable one by one or all at once.

Logs

The activity trail the SDK writes to, plus owner notes. Selectable rows, clearable.

Blacklist

HWIDs, addresses and usernames. A reason is appended to the refusal copy.

Messages

Every string a client sees on success and refusal. Editing here changes the API's answer.

Webhooks

Signed deliveries per event with a one-click test and the last attempt recorded.

Team

Invite by email with a role and an explicit permission list. Revocation is immediate.

Settings

Profile, avatar and frame, 2FA, passkeys, backup codes, token, sessions, plan and the Discord bot.

Docs

This page. Routes, SDK, webhooks and the bot, generated from the same surface the panel uses.

04

Roles and plans

Two plans and one role above them. Every new account is a user. Buying premium moves the plan. Admin is not a plan and is never granted from the panel — it is a flag flipped by hand in the database, and it opens every gate while leaving the stored plan alone.

User

The default. Three applications, one thousand keys, HWID locking, signed webhooks.

Premium

Unlimited applications, twenty-five thousand keys, the Discord bot, and the Files / Variables / Rules surfaces as they ship.

Admin

Set in the database. Every permission, every plan gate, every teammate check passes. Nothing in the UI can grant or remove it.

The admin flag is the only SQL you will need for it:

UPDATE users SET is_admin = true  WHERE username = 'your_name';
UPDATE users SET is_admin = false WHERE username = 'your_name';

Plans live in users.plan and only ever hold user or premium. An admin is shown as admin regardless of the stored plan.

05

SDK quickstart

Four steps from an empty file to a key that refuses to launch on a second machine. Nothing here needs a framework, and the verify call is the same two variables in every language.

Step 01

Create the application

One application per product. The panel issues a unique app id and a secret per app. Both travel with every verify call — the secret is what proves the call came from your build, so it lives in your build config, never in source. The values below are placeholders; yours are under Dashboard → Projects → your app → Settings.

id      XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
secret  your-app-secret-from-the-panel
Step 02

Set the credentials

There is no SDK to install and no build step. Two environment variables are the whole integration surface, and the same two work in every language below.

NOCT_APP_ID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
NOCT_SECRET=your-app-secret-from-the-panel

# .env, or the equivalent in your host's secret store
Step 03

Verify a key

Send the key with a machine fingerprint. The first call that carries one binds the key to that machine and starts the clock. The same key on another machine is refused, and a bound key with no fingerprint is refused too. Pick your language.

curl -s https://noct.wtf/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "key": "NOCT-9F3A-71C2-DE04",
    "ownerId": "your-app-id",
    "secret": "your-app-secret",
    "hwid": "39a1b2c3d4e5f607"
  }'

# 200 { "valid": true, "key": { "status": "active", "expires_at": "..." } }
# 403 { "valid": false, "error": "HWID mismatch - license is locked to another device" }
Step 04

Listen for the event

Redemptions, resets, bans, expiries and refusals post to the webhook URL on the app. Every delivery is signed with the app secret, so a handler that skips the HMAC check will act on anything that finds the URL.

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/webhooks/noct", express.raw({ type: "application/json" }), (req, res) => {
  const sent = req.get("x-noct-signature") ?? "";
  const expected = createHmac("sha256", process.env.NOCT_SECRET)
    .update(req.body)
    .digest("hex");

  const a = Buffer.from(sent, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString());
  if (event.type === "license.activated") grant(event.data);
  if (event.type === "license.revoked") revoke(event.data);

  res.sendStatus(200);
});
06

SDK endpoints

Both are public, both need the app id and the app secret, and both answer with `valid` plus whatever copy you typed under Messages. A refusal is still a JSON body, so a client can show the reason rather than a blank crash.

POST/api/v1/verifysecret

Binds a licence to one machine and returns `valid` plus the owner's copy.

{ "key", "ownerId", "secret", "hwid"?, "ip"?, "platform"?, "version"?, "components"? }
POST/api/v1/loginsecret

Signs a sub-user in and returns a session id.

{ "username", "password", "ownerId", "secret", "hwid"?, "ip"?, "platform"? }

verify — success

{
  "valid": true,
  "message": "Welcome back.",
  "key": {
    "status": "active",
    "hwid": "9f2c...c41a",
    "expires_at": "2027-04-01T00:00:00.000Z"
  }
}

verify — refused

{
  "valid": false,
  "error": "This key is already bound to another machine."
}

HWID binding

The first verify carrying a fingerprint binds it to the key and starts expiry. After that, a different fingerprint is refused with `hwid_mismatch` and the attempt is recorded with both machines so the panel can show them side by side.

Order of checks

Credentials, then app status, then blacklist (HWID, IP, username on login), then the key or user row: revoked, expired, HWID. The first failure wins and its message is yours.

Rate limits

120 calls per minute per address and 30 per minute per key on verify. Over either ceiling the answer is 429 with `Retry-After`.

Optional fields

`platform` is a free-form banner (OS, build, wine version) shown back in the panel. `components` is up to twelve name/value pairs describing what fed the fingerprint. Neither is trusted or parsed.

07

API reference

The routes that actually do the work: the ones you integrate against and operate an app with. Panel-only plumbing (icon uploads, live sessions, logs, blacklists, message copy, teammates, passkeys, preferences) is left out on purpose — it is internal, and documenting it would just be noise. Every route below reads the session cookie; there is no bearer token for the panel.

Accounts and sign-in

POST/api/auth/signup/startpublic

Checks the name and address, stages the account, mails a six-digit code.

{ "username", "email", "password", "acceptedLicense": true }
POST/api/auth/signup/verifypublic

Creates the account, mints the account token, mails it, signs the session in.

{ "email", "code" }
POST/api/auth/loginpublic

Mints a session. With 2FA on the answer is a challenge, then the same call carries `code`.

{ "email", "password", "remember" }
POST/api/auth/tokenpublic

Session from the account token alone. No password, no second factor, by design.

{ "token", "remember" }
POST/api/auth/otp/sendpublic

Mails a one-time code for a sign-in that needs a second factor.

{ "email" }
POST/api/auth/otp/verifypublic

Trades that code for the session the password step held back.

{ "email", "code" }
POST/api/auth/password-resetpublic

Mails a reset link. Always answers 200 so it cannot be used to probe accounts.

{ "email" }
POST/api/auth/password-reset/confirmpublic

Spends the link once and writes the new hash.

{ "token", "password" }
POST/api/auth/logoutsession

Clears both cookies and records the sign-out.

Applications, keys and users

POST/api/apps/createsession

Creates an application. Over the plan ceiling this is a 402 naming the upgrade.

{ "name", "version", "accepted": true }
PATCH/api/apps/:appIdsession

Renames or re-versions an application. A foreign id is a 404 before any write.

{ "name"?, "version"?, "description"? }
DELETE/api/apps/:appIdsession

Deletes the application and everything hanging off it. Irreversible.

GET/api/apps/:appId/credentialssession

The client id and secret, for the panel's copy buttons.

POST/api/apps/:appId/secretsession

Rotates the SDK secret. Builds holding the old one stop verifying immediately.

POST/api/apps/:appId/statussession

Pauses the app; every verify then refuses with the app's own disabled message.

{ "status": "active" | "paused" }
GET/api/apps/:appId/licensessession

Every key on the app with status, HWID, expiry and usage.

POST/api/apps/:appId/licensessession

Generates keys in bulk. The mask decides the shape, e.g. XXXX-XXXX-XXXX-XXXX.

{ "mask", "amount", "expiryDuration", "expiryUnit", "lower", "upper", "note" }
PATCH/api/apps/:appId/licensessession

Resets a HWID (`action: "reset-hwid"`), bans or re-labels one key.

{ "licenseId", "action"?, "status"?, "note"?, "expiryDuration"?, "expiryUnit"? }
DELETE/api/apps/:appId/licensessession

Removes one key.

{ "licenseId" }
GET/api/apps/:appId/licenses/:licenseIdsession

One key with its attempt history — the machine it was refused on, next to the bound one.

GET/api/apps/:appId/userssession

Sub-users of the app: status, expiry, HWID lock, last seen.

POST/api/apps/:appId/userssession

Creates a sub-user the app's own login screen can authenticate.

{ "username", "email", "password" }
PATCH/api/apps/:appId/userssession

Resets a password or HWID, changes expiry, bans or re-enables.

{ "userId", "action"?, "password"?, "expiresAt"?, "hwidLocked"?, "status"?, "username"?, "email"? }
DELETE/api/apps/:appId/userssession

Deletes a sub-user.

{ "userId" }
GET/api/apps/:appId/users/:userIdsession

One sub-user with their session history.

GET/api/apps/:appId/webhookssession

Webhook endpoints plus the last delivery attempt for each.

POST/api/apps/:appId/webhookssession

Registers an endpoint. Only `https` URLs are accepted.

{ "url", "events": string[] }
PATCH/api/apps/:appId/webhookssession

Edits the URL, the subscribed events, or switches delivery off.

{ "id", "url"?, "events"?, "enabled"? }
DELETE/api/apps/:appId/webhookssession

Removes the endpoint.

{ "id" }
POST/api/apps/:appId/webhooks/testsession

Sends one signed `Test` delivery so a handler can be proven end to end.

{ "id" }
GET/api/account/tokensession

The account token behind the reveal in Settings. Minted on first read after signup.

POST/api/account/tokensession

Issues a new token and mails it. Every bot and client holding the old one stops working.

{ "action": "rotate" }
PATCH/api/account/profilesession

Both unique across the table; the session is reissued with the new values.

{ "username"?, "email"? }
POST/api/account/passwordsession

The current password is required even with a live session.

{ "currentPassword", "newPassword" }
POST/api/account/totpsession

The whole 2FA wizard. `enable` is the only call that flips the flag; `backup-generate` returns ten codes once.

{ "action": "begin" | "check" | "send-code" | "verify-password" | "enable" | "backup-generate" | "disable", "code"?, "emailCode"?, "password"? }
POST/api/account/plansession

Records the plan. No processor is wired in, so nothing is charged.

{ "plan": "user" | "premium" }
GET/api/account/discordsession

The linked Discord account, or null.

POST/api/account/discordsession

Cuts the bot off for this account. The bot refuses until a new `/login` lands.

{ "action": "unlink" }
POST/api/account/deletesession

Permanent. Name + password, plus the authenticator code when 2FA is on.

{ "password", "confirm", "code"? }

Bot

POST/api/bot/loginsecret

Header `x-bot-key` must match the deployment's shared secret. Trades an account token for the briefing. Premium (or admin) only; one Discord id maps to one account.

{ "token", "discordId"?, "discordTag"? }
08

Webhooks

One POST per interesting event, to every endpoint subscribed to it. The body is JSON, the signature is an HMAC-SHA256 of the exact bytes over the app secret, and a handler that skips the check will act on anything that finds the URL.

user_loginUser LoginA key or sub-user verified successfully.
login_failedLogin FailedThe key or credentials were wrong.
hwid_mismatchHWID MismatchA real key from a machine it is not bound to.
login_blocked_hwidLogin Blocked (HWID)The fingerprint is blacklisted.
login_blocked_ipLogin Blocked (IP)The address is blacklisted.
login_blocked_usernameLogin Blocked (Username)The sub-user name is blacklisted.
account_expiredAccount ExpiredThe key or sub-user ran out of time.
account_disabledAccount DisabledThe app is paused or the account is banned.
version_mismatchVersion MismatchThe client reported a different build number.
key_resetKey ResetThe HWID was reset from the panel.
testTestFired by the panel's test button.

Headers

Content-Type: application/json
X-Noct-Event: user_login
X-Noct-Signature: 8c1e...a904

Body

{
  "type": "user_login",
  "title": "User Login",
  "detail": "Welcome back.",
  "identity": "ABCD-EFGH-...",
  "hwid": "9f2c...c41a",
  "ip": "203.0.113.4",
  "platform": "Windows 11 26100",
  "extra": [{ "label": "Expires", "value": "..." }]
}

Deliveries in 429 and 5xx are retried once after a short delay; a 4xx is a configuration error and is not retried. Every attempt is written to the delivery table, so the panel can show what actually arrived.

09

Discord bot

A hosted bot, not one you run. Invite it once, run /login in a channel only you can see, paste an account token into the modal, and it answers with the account's live state. It never stores the token and never posts it.

  1. 01Open Settings, Billing, then the Discord bot card. The invite button is locked until the account is Premium or admin.
  2. 02Add the bot with the five permissions it asks for: View Channels, Send Messages, Embed Links, Read Message History, Use Application Commands.
  3. 03Run /login. The modal takes the account token from Settings, General. The token is traded once and discarded.
  4. 04The embed answers from the panel: every application with active/total keys and users, plan, member-since, 2FA and backup-code state, and the last sign-in.
  5. 05To cut the bot off, rotate the token or hit Unlink. Either one empties the briefing for that account until a new /login lands.
POST /api/bot/login
x-bot-key: <shared secret>
{
  "token": "nct_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "discordId": "123456789012345678",
  "discordTag": "name"
}

200 {
  "ok": true,
  "account":   { "id", "username", "email", "plan", "createdAt" },
  "security":  { "twoFactor", "backupCodes", "passkeys" },
  "applications": [{ "id", "name", "version", "licenses", "activeLicenses", "users" }],
  "totals":    { "applications", "licenses", "users" },
  "discord":   { "id", "tag", "linkedAt" } | null,
  "lastSignIn":{ "kind", "detail", "ip", "createdAt" } | null
}

401 bad or missing key / unknown token
402 plan below premium
409 that Discord id is already linked to another account
10

Errors and limits

Two shapes only. The panel speaks `{ error }` for a failure and `{ ok, ... }` for a success; the SDK speaks `{ valid, error }` so a client can branch on one boolean and still show the owner's copy.

200Done. The body carries the result.
400Malformed JSON or a missing required field.
401No session, or the app id / secret pair is wrong.
402The plan or an admin gate refuses this action. The body names the plan.
403Authenticated, but the key, machine or account is refused — the owner's own copy.
404The row does not exist, or does not belong to this account.
409A unique value is already taken (name, email, Discord id).
422Well-formed but rejected on content — unknown frame, unknown plan, bad code.
429Rate limited. `Retry-After` says how many seconds to wait.
503A feature is not configured on this deployment (mail, bot key).

Pictures

2 MB maximum, PNG / JPEG / GIF / WebP, sniffed by magic bytes rather than the extension. Stored under the sha256 of the bytes, so the same image is one object.

Account token

`nct_` plus 32 characters from the URL-safe alphabet. Unique in the table, never rendered in a page payload, fetched only on reveal.

Backup codes

Ten codes of the form XXXXX-XXXXX from a 32-character alphabet without lookalikes. Only the sha256 is stored; the plaintext exists for one render.

Sub-user passwords

Hashed with the same scrypt parameters as panel accounts. A reset is a write, never a read — nothing can return the old value.