Skip to main content
BunShip supports TOTP-based two-factor authentication (2FA) using authenticator apps such as Google Authenticator, Authy, or 1Password. The setup flow has three steps: initiate setup, scan the QR code, then verify a code to activate.

​
Setup 2FA

Requires a valid Bearer token.
POST /api/v1/auth/two-factor/setup
Generates a TOTP secret, QR code, and backup recovery codes. The user must scan the QR code with an authenticator app and then call the verify endpoint to finalize activation.

​
Request Body

​
password
string
required
Current account password to confirm identity.

​
Response

​
secret
string
TOTP secret string for manual entry into the authenticator app.
​
qrCode
string
Base64-encoded data URL of the QR code image.
​
backupCodes
string[]
One-time backup codes for account recovery if the authenticator device is lost.
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "backupCodes": [
    "a1b2c3d4e5",
    "f6g7h8i9j0",
    "k1l2m3n4o5",
    "p6q7r8s9t0",
    "u1v2w3x4y5",
    "z6a7b8c9d0",
    "e1f2g3h4i5",
    "j6k7l8m9n0"
  ]
}

​
Errors

StatusCodeDescription
401AUTHENTICATION_ERRORInvalid password
409CONFLICT2FA is already enabled on this account

​
Example

curl -X POST https://api.bunship.com/api/v1/auth/two-factor/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"password": "SecureP@ssw0rd"}'

​
Verify and Enable 2FA

Requires a valid Bearer token.
POST /api/v1/auth/two-factor/verify
Verifies a TOTP code from the authenticator app and permanently enables 2FA on the account. Must be called after the setup endpoint.

​
Request Body

​
code
string
required
6-digit code from the authenticator app. Must be exactly 6 numeric digits.

​
Response

​
message
string
Confirmation message.
{
  "message": "Two-factor authentication enabled successfully."
}

​
Errors

StatusCodeDescription
401AUTHENTICATION_ERRORInvalid TOTP code
404NOT_FOUNDNo pending 2FA setup found — call setup first
409CONFLICT2FA is already active

​
Example

curl -X POST https://api.bunship.com/api/v1/auth/two-factor/verify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

​
Disable 2FA

Requires a valid Bearer token.
POST /api/v1/auth/two-factor/disable
Disables two-factor authentication. Requires both the current password and a valid TOTP code to confirm the action.

​
Request Body

​
password
string
required
Current account password.
​
code
string
required
Current 6-digit code from the authenticator app. Must be exactly 6 numeric digits.

​
Response

​
message
string
Confirmation message.
{
  "message": "Two-factor authentication disabled successfully."
}

​
Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid TOTP code
401AUTHENTICATION_ERRORInvalid password
404NOT_FOUND2FA is not enabled on this account

​
Example

curl -X POST https://api.bunship.com/api/v1/auth/two-factor/disable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecureP@ssw0rd",
    "code": "123456"
  }'