commit 78fad18dcbb4a6917426c15d182bc89ffe527eeb
parent 24206706cfbbeb93a321e1f7501a0cc3b4d2ff39
Author: Antoine A <>
Date: Thu, 18 Sep 2025 19:06:18 +0200
corebank: new 2FA API
Diffstat:
| M | core/api-corebank.rst | | | 136 | ++++++++++++++++++++++++++++++++++++++++++++++--------------------------------- |
1 file changed, 80 insertions(+), 56 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -31,23 +31,24 @@ Introduction
The Libeufin bank provides a minimal core banking system. In addition to that,
it provides features for local/regional currencies.
----------------
Version History
---------------
-The current protocol version is ``v8``.
+The current protocol version is ``v10``.
Android cashier app is currently targeting ``v9``.
**Version history:**
+* ``v10`` (in development): Update two factor authentication API to match Merchant Backend API
+
Config
------
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **v9**.
+ This specification corresponds to ``current`` protocol being version **v10**.
**Response:**
@@ -172,7 +173,7 @@ The user ``admin`` is a special, hard-coded username. Some requests require the
:http:statuscode:`200 Ok`:
Response is a `TokenSuccessResponse`.
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`401 Unauthorized`:
Invalid or missing credentials.
:http:statuscode:`403 Forbidden`:
@@ -464,7 +465,7 @@ Account Management
**Response:**
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`204 No content`:
Operation successful.
:http:statuscode:`401 Unauthorized`:
@@ -505,7 +506,7 @@ Account Management
**Response:**
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`204 No content`:
Operation successful.
:http:statuscode:`404 Not found`:
@@ -532,7 +533,7 @@ Account Management
**Response:**
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`204 No content`:
The account was successfully deleted.
:http:statuscode:`401 Unauthorized`:
@@ -922,7 +923,7 @@ Transactions
:http:statuscode:`200 Ok`:
The bank responds with an `CreateTransactionResponse` object.
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`400 Bad Request`:
The request was invalid or the payto://-URI used unacceptable features.
:http:statuscode:`401 Unauthorized`:
@@ -1026,7 +1027,7 @@ Account withdrawals
**Response:**
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`204 No content`:
The withdrawal operation has been confirmed.
:http:statuscode:`401 Unauthorized`:
@@ -1184,7 +1185,7 @@ Cashouts
The cashout request was correctly created.
This returns the `CashoutResponse` response.
:http:statuscode:`202 Accepted`:
- 2FA is required for this operation. This returns the `Challenge` response.
+ 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
:http:statuscode:`401 Unauthorized`:
Invalid or missing credentials.
:http:statuscode:`403 Forbidden`:
@@ -1567,8 +1568,67 @@ Conversion rate class
classes: ConversionRateClass[];
}
-2FA
----
+
+Two Factor Auth
+---------------
+
+202 Challenge Responses
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor
+authentication (MFA) is required. In this case, the response will be a
+`ChallengeResponse`. In these cases, the client must first request and solve
+one or more challenges before repeating the request. When repeating the
+request, they must include a list of comma-separated challenge IDs of the
+solved challenges in an ``Taler-Challenge-Ids`` HTTP header. The body must
+remain absolutely unchanged.
+
+.. note::
+
+ If all allowed attempts to solve the MFA challenge(s) fail, the endpoint
+ may start to return ``403 Forbidden`` until the issued challenges expire,
+ preventing the request from being completed for a while. In this case,
+ repeating the request with a different body may still be allowed!
+
+.. ts:def:: ChallengeResponse
+
+ // @since v10
+ interface ChallengeResponse {
+ // List of challenge IDs that must be solved before the
+ // client may proceed.
+ challenges: Challenge[];
+
+ // True if **all** challenges must be solved (AND), false if
+ // it is sufficient to solve one of them (OR).
+ combi_and: boolean;
+ }
+
+.. ts:def:: Challenge
+
+ // @since v10
+ interface Challenge {
+ // Unique identifier of the challenge to solve to run this protected
+ // operation.
+ challenge_id: string;
+
+ // Channel that will be used to transmit the challenge.
+ tan_channel: TanChannel;
+
+ // Hint to show to the user as to where the challenge will be
+ // sent or what to use to solve the challenge. May not
+ // contain the full address for privacy.
+ tan_info: string;
+ }
+
+.. ts:def:: TanChannel
+
+ enum TanChannel {
+ SMS = "sms",
+ EMAIL = "email"
+ }
+
+Requesting challenges
+^^^^^^^^^^^^^^^^^^^^^
.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID
@@ -1576,7 +1636,7 @@ Conversion rate class
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 endpoints is not authenticated for token creation challenges.
+ This endpoint is not authenticated. @since **v10**
**Request:**
@@ -1584,12 +1644,8 @@ Conversion rate class
**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.
+ :http:statuscode:`204 No Content`:
+ The TAN code has bee
:http:statuscode:`404 Not Found`:
The challenge was not found.
:http:statuscode:`429 Too many requests`:
@@ -1597,44 +1653,16 @@ Conversion rate class
:http:statuscode:`502 Bad Gateway`:
* ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed.
- **Details:**
-
- .. ts:def:: TanTransmission
-
- interface TanTransmission {
- // 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;
- }
-
- .. ts:def:: TanChannel
-
- enum TanChannel {
- SMS = "sms",
- EMAIL = "email"
- }
-
-
+Solving challenges
+^^^^^^^^^^^^^^^^^^
+
.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm
Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
- 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 ``Taler-Challenge-Ids`` HTTP header and an 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. Too many unsuccessful attempts to confirm token creation challenges block the account.
**Request:**
@@ -1649,10 +1677,6 @@ Conversion rate class
: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.
:http:statuscode:`409 Conflict`:
