MFAService

Verify TOTP Challenge

Verify a TOTP code for session elevation or fresh step-up.

Method

POST

Path

/v1/auth/mfa/challenges/{challenge_id}:verify-totp

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

/v1/auth/mfa/challenges/{challenge_id}:verify-totp

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/auth/mfa/challenges/mfa_11111111111111111111111111111111:verify-totp' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "123456"
}'

Responses

{
  "accessToken": "eyJhbGciOiJFZERTQSJ9.example.signature",
  "accessTokenExpiresAt": "2025-01-01T00:00:00Z",
  "session": {
    "authTime": "2025-01-01T00:00:00Z",
    "authenticationMethods": [
      "totp"
    ],
    "sessionId": "session_01J0EXAMPLE",
    "sessionLevel": "PRIMARY_AUTHENTICATED"
  },
  "stepUpExpiresAt": "2025-01-01T00:00:00Z",
  "stepUpToken": "eyJhbGciOiJFZERTQSJ9.step-up.signature"
}

challenge_id string required 1-64 chars /^mfa_[…]{32}$/

Challenge identifier returned by BeginMFAChallenge.

code string required /^[0-9]{6,8}$/

Current 6 to 8 digit code from the authenticator app.

4 fields

accessToken string

MFA-elevated session token returned after every successful challenge.

Example eyJhbGciOiJFZERTQSJ9.example.signature

accessTokenExpiresAt string (date-time)

Time when access_token expires.

Example 2025-01-01T00:00:00Z

stepUpToken string

Fresh step-up token returned for fresh step-up challenges. Empty for session-elevation challenges.

Example eyJhbGciOiJFZERTQSJ9.step-up.signature

stepUpExpiresAt string (date-time)

Time when step_up_token expires. Empty when no step_up_token is returned.

Example 2025-01-01T00:00:00Z

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

POST

/v1/auth/mfa/challenges/{challenge_id}:verify-totp

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/auth/mfa/challenges/mfa_11111111111111111111111111111111:verify-totp' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "123456"
}'

Responses

{
  "accessToken": "eyJhbGciOiJFZERTQSJ9.example.signature",
  "accessTokenExpiresAt": "2025-01-01T00:00:00Z",
  "session": {
    "authTime": "2025-01-01T00:00:00Z",
    "authenticationMethods": [
      "totp"
    ],
    "sessionId": "session_01J0EXAMPLE",
    "sessionLevel": "PRIMARY_AUTHENTICATED"
  },
  "stepUpExpiresAt": "2025-01-01T00:00:00Z",
  "stepUpToken": "eyJhbGciOiJFZERTQSJ9.step-up.signature"
}