Returns a generic response regardless of success/failure to prevent account enumeration. If email service is configured, sends a verification email. Rate limited to 3 per IP per hour.

// Response (202 Accepted)
{
  "success": true,
  "data": {
    "message": "If this email is not already registered, you will receive a verification link shortly.",
    "requireVerify": true
  }
}

Rate limited to 5 attempts per IP+username per 15 minutes. If 2FA is enabled and no code is provided, returns requires2FA: true. If email is unverified, returns requireVerify: true.

// Success Response
{
  "data": {
    "token": "eyJhbGciOi...",
    "account": { "id": "...", "username": "...", "email": "...",
                 "role": "user", "twoFactorEnabled": false }
  }
}

// 2FA Required Response
{ "success": false, "requires2FA": true, "message": "Two-factor authentication code required" }

// Unverified Email Response (403)
{ "success": false, "requireVerify": true, "message": "Please verify your email address before logging in." }

Returns the authenticated account details including plan info, API usage, and application count. Requires Bearer token.

// Response
{
  "data": {
    "id": "...", "email": "[email protected]", "username": "john",
    "role": "user", "apiKey": "sa_...xyz1",
    "emailVerified": true, "twoFactorEnabled": false,
    "lastLoginAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z",
    "applicationCount": 2,
    "plan": {
      "name": "free", "displayName": "Free", "priceMonth": 0,
      "limits": { "maxApps": 1, "maxUsersPerApp": 15, "maxApiCallsMonth": 2500, "webSocketAccess": false }
    },
    "apiCallsUsed": 150,
    "apiCallsResetAt": "2025-02-01T00:00:00Z"
  }
}

Requires Bearer token. Accepts either the current password or a 2FA code (if 2FA is enabled) for verification.

// Response
{ "success": true, "data": { "message": "Password changed" } }

Verifies the account email using the token sent during registration. On success, automatically signs in the user and returns a JWT.

// Response
{
  "data": {
    "message": "Email verified successfully",
    "account": { "id": "...", "email": "...", "username": "...", "role": "user" },
    "token": "eyJhbGciOi..."
  }
}

Generates a new verification token and sends a verification email. Returns a generic message regardless of whether the account exists (prevents enumeration).

// Response
{ "success": true, "data": { "message": "If an account with that email exists, a verification email has been sent." } }

Sends a password reset email. Returns a generic response regardless of whether the account exists. Rate limited to 2 requests per IP per 24 hours.

// Response
{ "success": true, "data": { "message": "If an account with that email exists, a password reset link has been sent." } }

Resets the account password using a token from the password reset email. Token expires after 1 hour and is single-use.

// Response
{ "success": true, "data": { "message": "Password has been reset successfully. You can now log in." } }

Reset password using username + TOTP code for users who have 2FA enabled but lost email access. Rate limited to 2 requests per IP per 24 hours.

Revokes the current JWT token by adding it to a blocklist. The token will be rejected on subsequent requests until it naturally expires. Requires Bearer token.

// Response
{ "success": true, "data": { "message": "Logged out" } }

Generates a new API key for the authenticated account. The old key is immediately invalidated. Requires Bearer token.

// Response
{ "data": { "apiKey": "sa_new_key_here..." } }

Generates a TOTP secret and returns it along with the otpauth URL for QR code scanning. The secret is stored but 2FA is not enabled until verified with /2fa/enable. Requires Bearer token.

// Response
{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauth": "otpauth://totp/SwiftAuth:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=SwiftAuth"
  }
}

Verifies the TOTP code and enables 2FA on the account. Must call /2fa/setup first. Requires Bearer token.

// Response
{ "success": true, "data": { "message": "2FA enabled successfully" } }

Disables 2FA. Requires both the current password and a valid TOTP code for security. Requires Bearer token.

// Response
{ "success": true, "data": { "message": "2FA disabled" } }

Returns all available subscription plans with pricing and feature limits. No authentication required.

// Response
{
  "data": [
    {
      "name": "free",
      "displayName": "Free",
      "priceMonth": 0,
      "limits": {
        "maxApps": 1,
        "maxUsersPerApp": 15,
        "maxApiCallsMonth": 2500,
        "webSocketAccess": false,
        "features": ["users", "licenses", "devices", "logs"]
      }
    },
    { "name": "pro", "displayName": "Pro", "priceMonth": 4.99, ... },
    { "name": "business", "displayName": "Business", "priceMonth": 9.99, ... }
  ]
}

Returns all applications owned by the authenticated account with resource counts.

// Response
{
  "data": [{
    "id": "...", "name": "MyApp", "secret": "***abc123",
    "enabled": true, "version": "1.0.0", "paused": false,
    "antiDebug": false, "antiVM": false, "description": "",
    "createdAt": "...", "updatedAt": "...",
    "counts": { "users": 150, "licenses": 500, "sessions": 42,
                "variables": 10, "files": 3, "tokens": 5, "rules": 2 }
  }]
}

Creates a new application. Subject to plan limits on max applications.

// Response (201 Created)
{
  "data": {
    "id": "...", "name": "MyApp", "secret": "full_secret_shown_only_on_creation",
    "enabled": true, "version": "1.0.0", "description": ""
  }
}

Returns a single application's details. The secret is masked (last 6 characters only).

// Response
{
  "data": {
    "id": "...", "name": "MyApp", "secret": "***abc123",
    "enabled": true, "paused": false, "version": "1.0.0",
    "antiDebug": false, "antiVM": false,
    "lockHwid": false, "lockIp": false, "lockPcName": false,
    "description": "", "createdAt": "...", "updatedAt": "..."
  }
}

Update any combination of application settings.

Permanently deletes the application and all associated data (users, licenses, sessions, variables, files, rules, logs, integrations).

Generates a new secret key for the application. The old secret is immediately invalidated. All SDK clients will need the new secret to call /api/client/init.

// Response
{ "data": { "secret": "new_full_secret_48chars..." } }

Returns aggregate statistics for the application including user, license, session, and login counts.

// Response
{
  "data": {
    "users": { "total": 150, "active": 120, "banned": 5 },
    "licenses": { "total": 500, "used": 300, "unused": 200 },
    "sessions": { "active": 42 },
    "logins": { "today": 85, "thisWeek": 450 }
  }
}

Returns user with preloaded devices and subscriptions.

Accepts any combination of: password, email, level, expiresAt, deviceLimit, enabled, banned, banReason, hwid, displayName, pcName, lockedIp, hwidResetMax, hwidResetCooldown, ipResetMax, ipResetCooldown, metadata.

Permanently removes the user.

Clears HWID, locked IP, and all registered devices. Respects per-user cooldown and max reset limits.

Returns the user's last login IP and locked IP. Admin only — requires the account to have the admin role.

// Response
{ "data": { "lastLoginIp": "1.2.3.4", "lockedIp": "1.2.3.4" } }

Deletes all active sessions for the specified user. Also sends a force_logout event via WebSocket if the user is connected.

// Response
{ "data": { "deleted": 3 } }

Returns the license details if valid, or an error if not found/expired/banned.

Accepts: level, maxUses, duration, deviceLimit, displayName, note, enabled, banned.

Permanently removes the license key.

Returns full details for a single license key.

Delete multiple licenses at once, either by IDs or by filter. Provide ids for specific deletions, or filter for bulk cleanup.

// Response
{ "data": { "deleted": 15 } }

Returns IP and device info for the user who activated this license. Admin only — requires the account to have the admin role.

// Response
{
  "data": {
    "lastLoginIp": "1.2.3.4", "lockedIp": "1.2.3.4",
    "hwid": "ABC123...", "pcName": "DESKTOP-XYZ"
  }
}

Removes a registered device, allowing the user to authenticate from a new device.

Update token properties.

Permanently removes the token.

Returns all variables sorted by key.

Permanently removes the variable.

Returns all variables for the specified user, sorted by key.

Pushes a user_variable_update event to the user via WebSocket if connected.

Permanently removes the variable. Pushes a user_variable_delete event via WebSocket.

Returns all variables attached to the specified license, sorted by key.

Value is validated against the specified type. Duplicate keys within the same license are rejected.

Permanently removes the variable from the license.

Returns all uploaded files for the application.

Use multipart/form-data with field file. Optional fields: name, version.

Returns the file as a binary download with Content-Disposition header.

Permanently removes the file from storage and database.

Create multiple rules at once.

Permanently removes the rule.

// Response
{
  "data": {
    "total": 1250, "byLevel": { "INFO": 900, "WARNING": 200, "ERROR": 150 },
    "byEvent": { "user.login": 500, "session.init": 300, ... }
  }
}

Returns all distinct event types that have been logged for this application.

// Response
{ "data": ["user.login", "user.register", "session.init", "license.activate", ...] }

Deletes log entries older than the specified number of days.

// Response
{ "data": { "deleted": 500 } }

Returns all integrations for the application. Webhook URLs are masked for security.

Returns all event types that can be subscribed to via integrations.

// Response
{ "data": [
  "user.login", "user.login_failed", "user.register", "user.create", "user.update",
  "user.delete", "user.ban", "user.extend", "user.hwid_reset", "user.session_kill",
  "license.activate", "license.create", "license.update", "license.delete",
  "session.init", "session.end", "token.validate", "token.create", "token.delete",
  "file.upload", "file.download", "file.update", "file.delete",
  "variable.create", "variable.update", "variable.delete",
  "rule.create", "rule.update", "rule.delete", "rule.triggered",
  "integration.create", "integration.update", "integration.delete",
  "app.update", "app.secret_reset"
] }

Permanently removes the integration.

Sends a test webhook to the integration's configured URL. Supports Discord embeds, Telegram messages, Slack attachments, and custom JSON payloads.

// Response
{ "success": true, "data": { "message": "Test webhook sent" } }

Generates a new signing secret for CUSTOM type integrations. The old secret is immediately invalidated.

// Response
{ "data": { "secret": "new_secret_32chars..." } }

Returns aggregate metrics for users, licenses, sessions, and activity within the specified period.

// Response
{
  "data": {
    "period": "24h",
    "users": { "total": 150, "new": 5, "active": 42, "banned": 3 },
    "licenses": { "total": 500, "unused": 200 },
    "sessions": { "active": 28 },
    "activity": { "logins": 85, "failedLogins": 12, "registrations": 5 }
  }
}

Returns event counts bucketed by hour or day for charting activity trends.

// Response
{ "data": [
  { "bucket": "2025-01-15", "count": 42 },
  { "bucket": "2025-01-16", "count": 55 },
  ...
] }

Returns login counts grouped by country code, based on IP geolocation data from log entries.

// Response
{ "data": [
  { "country": "US", "count": 250 },
  { "country": "GB", "count": 80 },
  ...
] }

Returns the most recent log entries for the application, useful for a live activity feed.

// Response
{ "data": [
  { "id": "...", "event": "user.login", "message": "User logged in",
    "username": "john", "ipAddress": "1.2.3.4", "level": "INFO",
    "createdAt": "2025-01-15T10:30:00Z" },
  ...
] }

// Response
{
  "data": {
    "sessionToken": "sess_abc123...",
    "app": { "name": "MyApp", "version": "1.0.0" }
  }
}

// Response
{ "data": { "nonce": "abc123..." } }

Requires X-Nonce header.

Requires X-Nonce header.

Authenticate using only a license key (no username/password). Requires X-Nonce header.

Activates a license key for the currently logged-in user. Requires X-Nonce header.

Checks if a license key is valid without activating it. Returns validity status, issues, and license details.

// Response
{
  "data": {
    "valid": true,
    "exists": true,
    "banned": false,
    "enabled": true,
    "issues": [],
    "license": {
      "level": 1,
      "duration": 2592000,
      "expiresAt": "2025-12-31T00:00:00Z",
      "usedCount": 1,
      "maxUses": 5,
      "usedBy": "user123"
    }
  }
}

Keep-alive ping. Must be called periodically to prevent session expiry. Requires X-Nonce header.

Validates if a session token is still active. Body: { "sessionToken": "..." }

Gracefully ends the session. Body: { "sessionToken": "..." }

Returns all variables for the application. Body: { "sessionToken": "..." }

Returns the value of a variable attached to the user's active license. Returns { key, value, type }.

Returns all variables attached to the user's active license. Body: { "sessionToken": "..." }

Response is an array of { key, value, type } objects.

Returns the value of a user-specific variable. Requires an authenticated (logged-in) session.

Returns all variables for the authenticated user. Body: { "sessionToken": "..." }

Creates or updates a user variable. If the key already exists, its value is overwritten (upsert).

Permanently deletes a user variable by key.

Compares the current version against the latest file version. Returns download URL if update available.

Returns the authenticated user's profile. Body: { "sessionToken": "..." }

Validates an application access token and increments its usage counter. Returns the token's level for permission checks.

// Response
{ "data": { "valid": true, "level": 1 } }

Allows the logged-in app user to change their password.

// Response
{ "success": true, "data": { "message": "Password changed" } }

Requests an HWID/IP reset for a user via their license key. Sends a confirmation email to the user's registered email. Respects per-user reset limits and cooldowns.

// Response
{ "success": true, "data": { "message": "Reset confirmation email sent" } }

Confirms the HWID/IP reset using the token from the confirmation email. Returns an HTML success page. Token is single-use and time-limited.

Upgrades the HTTP connection to a WebSocket. Authentication is done via the token query parameter (your JWT), since browsers cannot send custom headers during WebSocket upgrade.

On connect, the server automatically sends the current online_count and sessions list.

Sending Messages (Dashboard → Server)

Receiving Events (Server → Dashboard)

// Example: Connect to dashboard WebSocket
const ws = new WebSocket(
  `wss://swiftauth.net/api/apps/${appId}/ws/connect?token=${jwt}`
);

ws.onopen = () => {
  // Subscribe to specific events only
  ws.send(JSON.stringify({ type: "set_filters", events: ["chat", "session_connect"] }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "online_count") {
    console.log("Online users:", msg.data.count);
  }
};

// Send a chat message to a user
ws.send(JSON.stringify({ type: "chat", userId: "user_123", message: "Hello!" }));

Upgrades the HTTP connection to a WebSocket for client SDK users. Authenticated via the token query parameter (session token from login). The server enforces IP pinning, user state validation, and rule checks before allowing upgrade.

The server revalidates the session and user state every 30 seconds. If the session expires, user gets banned, or the app is paused/disabled, the server sends a force_logout event and closes the connection.

Sending Messages (Client → Server)

Receiving Events (Server → Client)

// Example: Connect as a client SDK user
const ws = new WebSocket(
  `wss://swiftauth.net/api/client/ws?token=${sessionToken}`
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "variable_update":
      console.log("Variable changed:", msg.data.key, "=", msg.data.value);
      break;
    case "variable_delete":
      console.log("Variable removed:", msg.data.key);
      break;
    case "user_variable_update":
      console.log("User variable:", msg.data.key, "=", msg.data.value);
      break;
    case "message":
      console.log(`[${msg.data.type}] ${msg.data.message}`);
      break;
    case "force_logout":
      console.log("Disconnected:", msg.data.reason);
      ws.close();
      break;
    case "banned":
      console.log("Banned:", msg.data.reason);
      ws.close();
      break;
    case "command":
      handleCommand(msg.data.command, msg.data.payload);
      break;
  }
};

// Set presence status
ws.send(JSON.stringify({ type: "set_status", status: "online" }));

// Send a chat message
ws.send(JSON.stringify({ type: "chat", message: "Hello from client!" }));

// Send a custom event (triggers hooks)
ws.send(JSON.stringify({ type: "player_score", data: { score: 1500, level: 3 } }));

Returns the number of currently connected client WebSocket users.

// Response
{ "success": true, "data": { "count": 42 } }

Returns all currently connected WebSocket sessions with user details.

// Response
{
  "success": true,
  "data": {
    "count": 2,
    "sessions": [
      { "userId": "...", "username": "john", "ip": "1.2.3.4", "connectedAt": "..." },
      { "userId": "...", "username": "jane", "ip": "5.6.7.8", "connectedAt": "..." }
    ]
  }
}

Send a message to all connected client WebSocket users.

// Response
{ "success": true, "data": { "sent": true, "onlineUsers": 42 } }

Send a force-logout event to a specific user, disconnecting them.

Kick a user from the WebSocket connection with an optional reason.

Ban a user (sets banned flag in database) and immediately disconnects them from WebSocket.

Send a chat message to a specific connected user.

Send a named command to a specific user or all connected clients. If userId is omitted, the command is broadcast to all clients.

Push a custom JSON payload to a specific user or all connected clients.

Returns all WebSocket hooks for the application, ordered by priority.

// Response
{
  "success": true,
  "data": {
    "count": 1,
    "hooks": [{
      "id": "...",
      "name": "Welcome Message",
      "event": "join_room",
      "conditions": [{ "field": "data.room", "operator": "eq", "value": "lobby" }],
      "actions": [{ "type": "respond", "message": "Welcome to the lobby!" }],
      "enabled": true,
      "priority": 0
    }]
  }
}

// Example: Create a hook
POST /api/apps/:appId/ws/hooks
{
  "name": "Auto-welcome",
  "event": "join_room",
  "conditions": [
    { "field": "data.room", "operator": "eq", "value": "lobby" }
  ],
  "actions": [
    { "type": "respond", "message": "Welcome to the lobby!" },
    { "type": "log", "message": "User joined lobby" }
  ]
}

Update any field of an existing hook. Only include the fields you want to change.

Permanently deletes a WebSocket hook.