Skip to main content

Biometric Login

Overview​

Authenticate a self-service customer using a previously registered biometric device token (e.g. fingerprint, Face ID). Biometric login bypasses the full password + OTP flow but is strictly bound to the registered device — the same deviceId and deviceToken pair that was used when biometric login was first activated.

Device-Switch Enforcement

If the X-Device-Id or X-Device-Token headers do not match the values stored when biometric login was activated, the server rejects the request with status code 45 and instructs the user to sign in with a password, confirm the device switch, and complete OTP verification before biometric login becomes available again on the new device.

Endpoint​

POST /api/BPMSelfService/commands/SelfBiometricLoginCommand

Request Headers​

All device headers are required for biometric login — they are the sole source of device identity. There is no body fallback.

HeaderRequiredExampleDescription
X-Device-IdYesa1b2c3d4-e5f6-...Unique device identifier registered during biometric activation
X-Device-TokenYesbio_tok_abc123...Biometric device token issued at activation time
X-App-ChannelYesMobileClient channel — defaults to Mobile if absent
X-Client-PlatformRecommendedAndroid / iOSDevice OS
X-App-VersionRecommended2.1.0App version
X-Device-HostOptionalSamsung Galaxy S24Device hostname / name
X-Device-ModelOptionalSM-G991BDevice model code
X-Ip-AddressOptional41.58.12.100Client IP
X-App-Build-NumberOptional210App build number
X-App-Package-NameOptionalcom.bank.appApp package / bundle identifier

Request Body Parameters​

ParameterTypeRequiredDescription
usernamestringYesCustomer username or email

No device or channel fields are read from the body — all must come from headers.

Device-Switch Flow​

When a user wants to use biometric login on a new device, they must:

  1. Sign in with password + OTP on the new device (SelfLoginCommand)
  2. Confirm the device switch through the app (which stores the new deviceId)
  3. Activate biometric on the new device (which issues a fresh deviceToken)
  4. Subsequent biometric logins on the new device will succeed

Response​

Successful Authentication​

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "...",
    "expiresIn": 3600
  }
}

Device Mismatch (Status 45)​

{
  "isSuccessful": false,
  "statusCode": "45",
  "message": "Biometric login is not available on this device. Please sign in with your password, confirm the device switch, and complete OTP verification to enable biometric on this device."
}

Missing Headers​

{
  "isSuccessful": false,
  "statusCode": "400",
  "message": "Device ID and device token are required headers for biometric login."
}

Example Usage​

const response = await fetch('/api/BPMSelfService/commands/SelfBiometricLoginCommand', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Device-Id': '550e8400-e29b-41d4-a716-446655440000',
    'X-Device-Token': 'bio_tok_abc123def456...',
    'X-App-Channel': 'Mobile',
    'X-Client-Platform': 'iOS',
    'X-App-Version': '2.1.0',
    'X-Device-Model': 'iPhone16,2'
  },
  body: JSON.stringify({
    username: 'customer@example.com'
  })
});

const result = await response.json();

if (!result.isSuccessful && result.statusCode === '45') {
  // Redirect user to password login → device-switch confirmation → OTP
  redirectToPasswordLogin({ requiresDeviceSwitch: true });
}

Security Notes​

  • X-Device-Token is cryptographically generated at biometric activation time and stored hashed on the server. It cannot be reused across devices.
  • Even if an attacker intercepts the token, they also need the matching X-Device-Id for the login to succeed.
  • Session DeviceInfo is stored as a JSON snapshot (user-agent, platform, model, IP, app version) for every biometric login — visible in audit logs.