Verify MFA code and complete authentication

1 min

POST

https://api.upstartcommerce.com/api/v1/auth/mfa/verify

Verifies the MFA code (TOTP, SMS OTP, or backup code) and completes the authentication process started by the login endpoint.

Upon successful verification, returns access and refresh tokens.

Body Parameters

bodyMfaVerifyRequestrequired
Example
```
{
  "challengeId": "ch_abc123xyz",
  "code": "123456"
}
```
Description
MFA verification details
- challengeIdstringrequired
  Example
  ch_abc123xyz
  Description
  MFA challenge ID from login response
- codestringrequired
  Example
  123456
  Description
  MFA verification code (TOTP, SMS OTP, or backup code)
  Min Length
  6
  Max Length
  10

Responses

200

MFA verification successful - tokens issued

AuthResponse
Example
```
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
```
Description
Successful authentication response containing tokens
- accessTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
  Description
  JWT access token for API authorization.
  
  Include in API requests as: Authorization: Bearer <accessToken>
  
  Claims:
  
  sub: User ID (UUID)
  
  type: Token type (consumer/management)
  
  roles: List of role identifiers
  
  tenant: Active tenant ID
  
  iat: Issued at (Unix timestamp)
  
  exp: Expiration (Unix timestamp)
  
  iss: Issuer (auth-svc)
- refreshTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
  Description
  Refresh token for obtaining new access tokens.
  
  Store securely (e.g., httpOnly cookie or secure storage). Use with /api/v1/auth/refresh when access token expires.
- expiresIninteger<int64>required
  Example
  3600
  Description
  Access token validity duration in seconds
  Format
  int64
- tokenTypestringrequired
  Example
  Bearer
  Description
  Token type (always "Bearer")

400Invalid request

ErrorResponse
Example
```
{
  "error": "invalid_request",
  "message": "Challenge ID and code are required",
  "code": "BAD_REQUEST"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

401Invalid MFA code or challenge expired

ErrorResponse
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

403Account locked due to too many failed attempts

ErrorResponse
Example
```
{
  "error": "forbidden",
  "message": "Account locked due to too many failed MFA attempts",
  "code": "FORBIDDEN"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

500Internal server error

ErrorResponse
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

curl

curl --request POST \
     --url https://api.upstartcommerce.com/api/v1/auth/mfa/verify \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "challengeId": "ch_abc123xyz",
     "code": "123456"
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "challengeId": "ch_abc123xyz",
   "code": "123456"
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/api/v1/auth/mfa/verify", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/api/v1/auth/mfa/verify")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "challengeId": "ch_abc123xyz",
   "code": "123456"
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/api/v1/auth/mfa/verify"

payload = json.dumps({
   "challengeId": "ch_abc123xyz",
   "code": "123456"
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// MFA verification successful - tokens issued
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

400

// Invalid request
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

401

// Invalid MFA code or challenge expired
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

GENERATED

// Invalid MFA code or challenge expired
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

invalidCode

// Invalid MFA code
{
  "error": "unauthorized",
  "message": "Invalid MFA code. 4 attempts remaining.",
  "code": "UNAUTHORIZED"
}

challengeExpired

// Challenge expired
{
  "error": "unauthorized",
  "message": "MFA challenge has expired. Please login again.",
  "code": "UNAUTHORIZED"
}

403

// Account locked due to too many failed attempts
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

500

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

GENERATED

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

tokenGenerationFailed

// Token generation failed
{
  "error": "internal_error",
  "message": "Token generation failed",
  "code": "INTERNAL_SERVER_ERROR"
}

serviceError

// Upstream service error
{
  "error": "internal_error",
  "message": "Failed to communicate with authentication backend",
  "code": "INTERNAL_SERVER_ERROR"
}