Authentication

---

​

Login

Authenticates a user and returns a JWT token along with user details.

• Endpoint: /api/auth/login
• Method: POST
• Body:
  • username (string, required): The user’s username.
  • password (string, required): The user’s password.
• Request Example:
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  
• Success Response:
  {
    "success": true,
    "message": "Login successful",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  
• Password login disabled: while Better Auth’s disablePasswordLogin is in effect, the endpoint answers 403 with {"success": false, "message": "Password login is disabled. Sign in with SSO, or use a bearer key for API access."}. See SSO-only sign-in.

---

​

Register

Registers a regular user and returns a JWT token. Requires systemConfig.auth.allowRegistration: true (default: false) and password login to be enabled; otherwise returns HTTP 403.

• Endpoint: /api/auth/register
• Method: POST
• Body:
  • username (string, required): The desired username.
  • password (string, required): The desired password (at least 8 characters, including a letter, a number, and a special character).
  • Administrator privileges cannot be requested; isAdmin is ignored.
• Request Example:
  {
    "username": "newuser",
    "password": "Password123!"
  }
  
• Success Response:
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "newuser",
      "isAdmin": false,
      "permissions": { ... }
    }
  }
  

---

​

Get Current User

Retrieves the profile of the currently authenticated user.

• Endpoint: /api/auth/user
• Method: GET
• Authentication: Bearer Token required.
• Success Response:
  {
    "success": true,
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  

---

​

Change Password

Allows the authenticated user to change their password.

• Endpoint: /api/auth/change-password
• Method: POST
• Authentication: Bearer Token required.
• Body:
  • currentPassword (string, required): The user’s current password.
  • newPassword (string, required): The desired new password (must be at least 6 characters).
• Request Example:
  {
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }
  
• Success Response:
  {
    "success": true,
    "message": "Password updated successfully"
  }
  

---

​

Social Login (Better Auth)

MCPHub integrates Better Auth to provide seamless social login capabilities (GitHub, Google, etc.). Prerequisites:

1. Database Mode: DB_URL environment variable must be configured (PostgreSQL is required for Better Auth persistence).
2. Provider Configuration: Better Auth bootstrap settings are read once at startup, so restart MCPHub after changing them.
3. Environment Variables:

• Global: BETTER_AUTH_ENABLED, BETTER_AUTH_URL, optional BETTER_AUTH_BASE_PATH, optional BETTER_AUTH_TRUSTED_ORIGINS.
• GitHub: BETTER_AUTH_GITHUB_ENABLED, GITHUB_CLIENT_ID, and GITHUB_CLIENT_SECRET.
• Google: BETTER_AUTH_GOOGLE_ENABLED, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET.
• Local OIDC: BETTER_AUTH_OIDC_ENABLED, optional BETTER_AUTH_OIDC_PROVIDER_ID, BETTER_AUTH_OIDC_DISCOVERY_URL (or legacy OIDC_DISCOVERY_URL), optional BETTER_AUTH_OIDC_SCOPES, optional BETTER_AUTH_OIDC_PKCE, optional BETTER_AUTH_OIDC_PROMPT, plus OIDC_CLIENT_ID and OIDC_CLIENT_SECRET.

Non-secret Better Auth settings can also be stored in systemConfig.auth.betterAuth, but the BETTER_AUTH_* environment variables take precedence over stored config values. Endpoints: The Better Auth handler is mounted at ${BASE_PATH}${betterAuthConfig.basePath}. The default betterAuthConfig.basePath is /api/auth/better; set BETTER_AUTH_BASE_PATH to override it at startup, or use systemConfig.auth.betterAuth.basePath as a fallback. BETTER_AUTH_URL takes precedence over systemConfig.install.baseUrl when MCPHub builds redirect URLs. If you also set BASE_PATH, prepend it to every example below. Key endpoints include:

• Initiate Login:
  • GET /api/auth/better/signIn/social?provider=github
  • GET /api/auth/better/signIn/social?provider=google
• Session Management:
  • GET /api/auth/better/session (Get current session)
  • POST /api/auth/better/signOut (Sign out)

For a complete list of endpoints and usage details, refer to the Better Auth API Documentation. Disabling Better Auth: Better Auth is automatically disabled if DB_URL is not configured, if BETTER_AUTH_ENABLED=false, or if no login providers are effectively enabled with their required credentials.