Skip to main content

Admin Login

Overview​

Authenticate administrators using email/username and password with two-factor authentication support.

Endpoint​

POST /api/BPMSelfService/commands/SelfAdminLoginCommand

Request Parameters​

ParameterTypeRequiredDescription
usernamestringYesAdministrator username or email
passwordstringYesAdministrator password
verificationMethodTypeintegerNo2FA method: 0=Default, 1=Email, 2=SMS, 3=Authenticator (default: 0)
otpCodestringConditionalOTP code for email/SMS verification
setupVerificationCodestringConditionalTOTP code for authenticator setup verification

Response​

Successful Login (Email/SMS OTP)​

{
  "status": "success",
  "message": "OTP sent successfully",
  "data": {
    "otpSent": true,
    "maskedEmail": "a***@example.com",
    "expiresIn": 300
  }
}

Successful Login (Authenticator - First Time)​

{
  "status": "success",
  "message": "Authenticator setup required",
  "data": {
    "requiresSetup": true,
    "qrCodeUrl": "otpauth://totp/BankLingo:admin@example.com?secret=ABC123XYZ&issuer=BankLingo",
    "secretKey": "ABC123XYZ"
  }
}

Successful Authentication Complete​

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "...",
    "expiresIn": 3600,
    "user": {
      "id": 123,
      "username": "admin",
      "email": "admin@example.com",
      "roles": ["Administrator"]
    }
  }
}

Example Usage​

C# Example​

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

JavaScript Example​

// Initial login
const loginResponse = await fetch('/api/BPMSelfService/commands/SelfAdminLoginCommand', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'admin@example.com',
    password: 'SecurePassword123!',
    verificationMethodType: 3
  })
});

const loginData = await loginResponse.json();

if (loginData.data.requiresSetup) {
  // Show QR code setup UI
  displayQRCode(loginData.data.qrCodeUrl);
  
  // After user completes setup
  const setupResponse = await fetch('/api/BPMSelfService/commands/SelfAdminLoginCommand', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: 'admin@example.com',
      password: 'SecurePassword123!',
      verificationMethodType: 3,
      setupVerificationCode: userEnteredCode
    })
  });
}

Error Responses​

StatusError CodeDescription
401AUTH_001Invalid username or password
401AUTH_002Invalid OTP code
401AUTH_003OTP expired
403AUTH_004Account locked due to multiple failed attempts
404AUTH_005User not found
400AUTH_006Invalid verification method type

Implementation Details​

See TOTP Implementation Summary for technical implementation details.

Security Considerations​

  • Always use HTTPS for authentication endpoints
  • Implement rate limiting to prevent brute force attacks
  • Store JWT tokens securely (HttpOnly cookies recommended)
  • Clear tokens on logout
  • Monitor failed login attempts

See Also​