MFAService
Begin MFA Challenge
Start session elevation or fresh step-up using an enrolled MFA factor.
Method
POST
Path
/v1/auth/mfa/challenges
Visibility
Authentication
Session token
MFA Requirement
Not required
POST
/v1/auth/mfa/challenges Request
Testnet
curl --request POST \ \
--url 'https://api.testnet.polyester.com/v1/auth/mfa/challenges' \
--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 '{
"purpose": "SESSION_ELEVATION"
}'Responses
{
"allowedFactorTypes": [
"TOTP"
],
"challengeId": "mfa_11111111111111111111111111111111",
"expiresAt": "2025-01-01T00:00:00Z",
"publicKey": {
"challenge": "Y2hhbGxlbmdlLWZvci1kb2Nz",
"rpId": "devnet.polyester.com"
}
} purpose string
Desired challenge outcome: session elevation or fresh step-up.
challengeId string
Challenge identifier to submit when verifying a factor. Format: "mfa_" followed by 32 lowercase hex characters.
Example
mfa_11111111111111111111111111111111 allowedFactorTypes enum[]
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
Example
["TOTP"] 1 field
2 fields
key string
TODO: description pending
6 fields
nullValue enum
Represents a null value.
NULL_VALUE
numberValue number
Represents a double value.
stringValue string
Represents a string value.
boolValue boolean
Represents a boolean value.
structValue object
Represents a structured value.
1 field
values object[]
Repeated field of dynamically typed values.
expiresAt string (date-time)
Time when this challenge expires.
Example
2025-01-01T00:00:00Z| Key | Status | Error | When |
|---|---|---|---|
| unauthenticated | 401 | Unauthenticated | Authentication required. |
| permission-denied | 403 | Permission Denied | Permission denied. |
| invalid-argument | 400 | Invalid Argument | Invalid argument. |
| not-found | 404 | Not Found | Not found. |
| unavailable | 503 | Unavailable | Service unavailable. |