MFAService
Begin TOTP Enrollment
Generate a TOTP secret and enrollment challenge for the caller.
Method
POST
Path
/v1/auth/mfa/totp:begin-enrollment
Visibility
Authentication
Session token
MFA Requirement
POST
/v1/auth/mfa/totp:begin-enrollment Request
Testnet
curl --request POST \ \
--url 'https://api.testnet.polyester.com/v1/auth/mfa/totp:begin-enrollment' \
--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 '{
"label": "Primary Authenticator"
}'Responses
{
"enrollmentId": "mfa_22222222222222222222222222222222",
"expiresAt": "2025-01-01T00:00:00Z",
"otpauthUri": "otpauth://totp/Polyester:trader_alpha?secret=JBSWY3DPEHPK3PXP&issuer=Polyester",
"secret": "JBSWY3DPEHPK3PXP"
} label string
Optional human-friendly label. Defaults to "Authenticator App" when empty. Maximum 128 characters.
enrollmentId string
Enrollment challenge identifier. Format: "mfa_" followed by 32 lowercase hex characters.
Example
mfa_22222222222222222222222222222222 secret string
Shared secret to enter into an authenticator app. Returned only when enrollment begins.
Example
JBSWY3DPEHPK3PXP otpauthUri string
Authenticator-app setup URI for QR-code display. Returned only when enrollment begins.
Example
otpauth://totp/Polyester:trader_alpha?secret=JBSWY3DPEHPK3PXP&issuer=Polyester expiresAt string (date-time)
Time when this enrollment 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. |