Get Authentication from Google Authenticator

This endpoint completes two-factor authentication using a Google Authenticator one-time password. It accepts the TOTP verification code along with optional device registration details and returns a Bearer token valid for 10 minutes. Use this step after initial credential-based login when 2FA is enabled for the partner account.

Endpoint

POST /api/auth/google/2FA

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a user account has Google Authenticator 2FA enabled and a time-based one-time password (TOTP) must be verified before the session token is issued. This is typically the second step in the authentication flow, called after the primary username/password login succeeds and the server signals that 2FA verification is required. Optionally, device details can be submitted alongside the code to register a trusted device and reduce future 2FA prompts.

Request Body

{
  "secret": "JBSWY3DPEHPK3PXP",
  "verificationCode": "482910",
  "oneTimeCode": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenDevice": "d3e4f5a6-b7c8-4d9e-a0f1-2b3c4d5e6f7a",
  "nameDevice": "Work Laptop"
}

Response

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expiration": "2026-06-08T15:30:00Z",
  "userId": 100042
}

Error Codes

Common Mistakes

• Submitting an expired TOTP code — Google Authenticator codes are valid for only 30 seconds; ensure device clocks are synchronized via NTP.
• Omitting verificationCode — the current TOTP code is the primary credential for this step and must be present.
• Reusing a oneTimeCode — these codes are single-use; re-submitting the same code after a successful or failed attempt will result in a 401 error.
• Not refreshing the Bearer token before it expires — tokens issued by this endpoint last 10 minutes; use POST /api/auth/refresh proactively.

Related Endpoints

• POST /api/auth/v2 — Initial username/password authentication that precedes this 2FA step.
• POST /api/auth/refresh — Refreshes an existing Bearer token before or after expiration.

Example

curl -X POST https://api.banking.netevia.dev/api/auth/google/2FA \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "JBSWY3DPEHPK3PXP",
    "verificationCode": "482910",
    "oneTimeCode": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenDevice": "d3e4f5a6-b7c8-4d9e-a0f1-2b3c4d5e6f7a",
    "nameDevice": "Work Laptop"
  }'