commit f7a7f584f1d6f8aeeb45fe1cf827635ff2553b67
parent 1e7e57c1537c7b1e5fd2801d189762ff3061bc86
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 2 Sep 2025 13:59:41 +0200
rework MFA spec
Diffstat:
| M | core/api-merchant.rst | | | 94 | +++++++++++++++++++++++++++++++++---------------------------------------------- |
1 file changed, 39 insertions(+), 55 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -260,75 +260,52 @@ such as the implemented version of the protocol and the currency used.
Two Factor Auth
---------------
-.. http:post:: [/instances/$INSTANCE]/auth-channels/$CHANNEL/validate
-
- Request the validation of a 2FA channel.
-
- @since **v21**
-
- This endpoint may be used even when mandatory TAN channels
- were not validated yet.
-
- :http:statuscode:`204 No Content`:
- The channel has been successfully validated.
- :http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
-
- .. ts:def:: Challenge
-
- interface Challenge {
- // Unique identifier of the challenge to solve to run this protected
- // operation.
- challenge_id: string;
- }
-
.. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID
Send TAN code for the ``CHALLENGE_ID`` challenge.
- @since **v21**
+ This request can be posted several times to trigger TAN retransmission when
+ the current code has expired or too many confirmation attempts have been
+ made.
- This request can be posted several times to trigger TAN retransmission when the current code has expired or too many confirmation attempts have been made.
+ This endpoint is not authenticated, it may be used even when mandatory TAN
+ channels were not validated yet.
- This endpoints is not authenticated for token creation challenges.
+ @since **v21**
- This endpoint may be used even when mandatory TAN channels
- were not validated yet.
+ **Request:**
+
+ The request body must be empty.
**Response:**
:http:statuscode:`200 OK`:
- The TAN code have been sent. This returns `TanTransmission` response.
- :http:statuscode:`401 Unauthorized`:
- Invalid or missing credentials.
- :http:statuscode:`403 Forbidden`:
- Missing rights.
+ The TAN code has been sent. This returns `MerchantTanTransmissionResponse`.
:http:statuscode:`404 Not Found`:
The challenge was not found.
+ Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_UNKNOWN``.
:http:statuscode:`429 Too many requests`:
- Too many challenges are active right now, you must wait or confirm current challenges.
+ Too many challenges are active right now,
+ you must wait or confirm current challenges.
:http:statuscode:`502 Bad Gateway`:
- * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed.
+ TAN transmition via ``tan_channel`` failed.
+ Returned with ``TALER_EC_MERCHANT_MFA_HELPER_EXEC_FAILED``.
**Details:**
- .. ts:def:: TanTransmission
+ .. ts:def:: MerchantTanTransmissionResponse
- interface TanTransmission {
+ interface MerchantTanTransmissionResponse {
// Channel of the last successful transmission of the TAN challenge.
tan_channel: TanChannel;
// Info of the last successful transmission of the TAN challenge.
+ // Hint to show to the user as to where the challenge was
+ // sent or what to use to solve the challenge. May not
+ // contain the full address for privacy.
tan_info: string;
}
- .. ts:def:: Challenge
-
- interface Challenge {
- // Unique identifier of the challenge to solve to run this protected
- // operation.
- challenge_id: string;
- }
.. http:post:: [/instances/$INSTANCE]/challenge/$CHALLENGE_ID/confirm
@@ -336,19 +313,24 @@ Two Factor Auth
@since **v21**
- When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and an empty request body.
+ When the challenge is confirmed, you can call the protected endpoint again
+ with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and the
+ original request body.
- This endpoints is not authenticated for token creation challenges. Too many unsuccessful attempts to confirm token creation challenges block the account.
+ This endpoints is not authenticated for token creation challenges. Too many
+ unsuccessful attempts to confirm token creation challenges block the
+ account.
This endpoint may be used even when mandatory TAN channels
were not validated yet.
**Request:**
- .. ts:def:: ChallengeSolve
+ .. ts:def:: MerchantChallengeSolveRequest
+
+ interface MerchantChallengeSolveRequest {
- interface ChallengeSolve {
- // The TAN code that solves $CHALLENGE_ID
+ // The TAN code that solves $CHALLENGE_ID.
tan: string;
}
@@ -356,17 +338,19 @@ Two Factor Auth
:http:statuscode:`204 No Content`:
The challenge is confirmed.
- :http:statuscode:`401 Unauthorized`:
- Invalid or missing credentials.
- :http:statuscode:`403 Forbidden`:
- Missing rights.
:http:statuscode:`404 Not Found`:
The challenge was not found.
+ Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_UNKNOWN``.
:http:statuscode:`409 Conflict`:
- * ``TALER_EC_BANK_TAN_CHALLENGE_FAILED`` : wrong TAN.
- * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN.
+ Wrong TAN, returned with an
+ error code of ``TALER_EC_MERCHANT_TAN_CHALLENGE_FAILED``.
+ :http:statuscode:`410 Gone`:
+ The challenge expired (but is still remembered by the merchant).
+ Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_EXPIRED``.
+ Note that this status code is not guaranteed, you may also get a 404.
:http:statuscode:`429 Too many requests`:
Too many failed confirmation attempts, a new TAN must be requested.
+ Returned with ``TALER_EC_MERCHANT_TAN_TOO_MANY_ATTEMPTS``.
----------
Wallet API
@@ -4953,7 +4937,7 @@ Creating token families
// Offset to subtract from the start time rounded to ``validity_granularity``
// to compute the actual start time for a key.
- // Default is zero.
+ // Default is zero.
start_offset: RelativeTime;
// Kind of the token family.
