auth.v1.MFAService

BeginMFAChallenge

Start an MFA challenge for session elevation or fresh step-up.

Method

POST

Path

auth.v1.MFAService/BeginMFAChallenge

Service

auth.v1.MFAService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

auth.v1.MFAService/BeginMFAChallenge

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/auth.v1.MFAService/BeginMFAChallenge' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "purpose": "MFA_CHALLENGE_PURPOSE_SESSION_ELEVATION"
}'

Responses

{
  "allowedFactorTypes": [
    "MFA_FACTOR_TYPE_TOTP"
  ],
  "challengeId": "mfa_11111111111111111111111111111111",
  "expiresAt": "2025-01-01T00:00:00Z",
  "publicKey": {
    "challenge": "Y2hhbGxlbmdlLWZvci1kb2Nz",
    "rpId": "devnet.polyester.com"
  }
}

Request

auth.v1.BeginMFAChallengeRequest

Response

auth.v1.BeginMFAChallengeResponse

purpose enum must be defined value

Desired challenge outcome: session elevation or fresh step-up.

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

Challenge identifier to submit when verifying a factor. Format: "mfa_" followed by 32 lowercase hex characters.

allowedFactorTypes enum[] max 8 items, unique

Factor types the caller may use for this challenge. Maximum 8 unique values.

MFA_FACTOR_TYPE_TOTP MFA_FACTOR_TYPE_PASSKEY MFA_FACTOR_TYPE_RECOVERY_CODE

1 field

expiresAt string (date-time)

Time when this challenge expires.

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.