commit 4ac5304d5b76981f99c8562b075e5edd7bb8fdc3
parent 44d6f6e78207108a6e07eb1461edb0a069193d5b
Author: Antoine A <>
Date: Mon, 18 Nov 2024 17:45:55 +0100
corebank: add account lockout in version 7
Diffstat:
| M | core/api-corebank.rst | | | 116 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
1 file changed, 102 insertions(+), 14 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -42,7 +42,7 @@ The user ``admin`` is a special, hard-coded username. Some requests require the
.. warning::
- Basic authentication for endpoints other than ``/accounts/$USERNAME/token`` has been deprecated and will no longer be supported in the next release.
+ Since **v7** Basic authentication for endpoints other than ``/accounts/$USERNAME/token`` has been deprecated and will no longer be supported in the next release.
.. http:post:: /accounts/$USERNAME/token
@@ -73,7 +73,14 @@ The user ``admin`` is a special, hard-coded username. Some requests require the
**Response:**
:http:statuscode:`200 Ok`:
- The response is a `TokenSuccessResponse`
+ Response is a `TokenSuccessResponse`.
+ :http:statuscode:`202 Accepted`:
+ 2FA is required for this operation. This returns the `Challenge` response.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ * ``TALER_EC_GENERIC_FORBIDDEN``: missing rights.
+ * ``TALER_EC_BANK_ACCOUNT_LOCKED``: account is locked and cannot create new token using its password.
**Details:**
@@ -96,6 +103,15 @@ The user ``admin`` is a special, hard-coded username. Some requests require the
**Authentication:** The client must authenticate with a valid access token.
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The token have been deleted.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
+
.. http:get:: /accounts/$USERNAME/tokens
Retrieve a subset of tokens related to $USERNAME.
@@ -114,6 +130,10 @@ The user ``admin`` is a special, hard-coded username. Some requests require the
Response is a `TokenInfos`.
:http:statuscode:`204 No content`:
No tokens.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Mmissing rights.
**Details:**
@@ -165,7 +185,7 @@ Config
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **v6**.
+ This specification corresponds to ``current`` protocol being version **v7**.
**Response:**
@@ -332,7 +352,9 @@ Account Management
Input data was invalid. For example, the client specified a invalid
phone number or e-mail address.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`409 Conflict`:
* ``TALER_EC_BANK_REGISTER_USERNAME_REUSE`` : username already used.
* ``TALER_EC_BANK_REGISTER_PAYTO_URI_REUSE`` : payto URI already used.
@@ -404,7 +426,9 @@ Account Management
:http:statuscode:`204 No content`:
Operation successful.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
@@ -444,7 +468,9 @@ Account Management
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`409 Conflict`:
* ``TALER_EC_BANK_NON_ADMIN_PATCH_MISSING_OLD_PASSWORD``: a non-admin user has tried to change their password whihout providing the current one.
* ``TALER_EC_BANK_PATCH_BAD_OLD_PASSWORD`` : provided old password does not match current password.
@@ -467,7 +493,9 @@ Account Management
:http:statuscode:`204 No content`:
The account was successfully deleted.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
@@ -563,7 +591,9 @@ Account Management
:http:statuscode:`204 No Content`:
No accounts were found for the given request.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
**Details:**
@@ -609,6 +639,11 @@ Account Management
// Is this a taler exchange account?
is_taler_exchange: boolean;
+ // Is the account locked.
+ // Defaults to false.
+ // @since **v7**
+ is_locked?: boolean;
+
// Opaque unique ID used for pagination.
// @since **v4**, will become mandatory in the next version.
row_id?: Integer;
@@ -635,7 +670,9 @@ Account Management
:http:statuscode:`200 OK`:
The bank responds with an `AccountData` object.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
@@ -682,6 +719,11 @@ Account Management
// Is this a taler exchange account?
is_taler_exchange: boolean;
+ // Is the account locked.
+ // Defaults to false.
+ // @since **v7**
+ is_locked?: boolean;
+
// Is 2FA enabled and what channel is used for challenges?
tan_channel?: TanChannel;
@@ -723,7 +765,9 @@ Transactions
:http:statuscode:`204 No content`:
No transaction found.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
@@ -744,7 +788,9 @@ Transactions
:http:statuscode:`200 OK`:
The bank responds with an `BankAccountTransactionInfo` object.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
@@ -810,7 +856,9 @@ Transactions
:http:statuscode:`400 Bad Request`:
The request was invalid or the payto://-URI used unacceptable features.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
@@ -843,6 +891,10 @@ Account withdrawals
:http:statuscode:`200 Ok`:
The bank responds with an `BankAccountCreateWithdrawalResponse` object.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
@@ -899,6 +951,10 @@ Account withdrawals
2FA is required for this operation. This returns the `Challenge` response.
:http:statuscode:`204 No content`:
The withdrawal operation has been confirmed.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The operation was not found.
:http:statuscode:`409 Conflict`:
@@ -917,6 +973,10 @@ Account withdrawals
:http:statuscode:`204 No content`:
The withdrawal operation has been aborted.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The withdrawal operation was not found.
:http:statuscode:`409 Conflict`:
@@ -1039,6 +1099,10 @@ Cashouts
This returns the `CashoutResponse` response.
:http:statuscode:`202 Accepted`:
2FA is required for this operation. This returns the `Challenge` response.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The account pointed by ``$USERNAME`` was not found.
:http:statuscode:`409 Conflict`:
@@ -1071,6 +1135,10 @@ Cashouts
:http:statuscode:`200 OK`:
Response is a `CashoutStatusResponse`.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not found`:
The cashout operation was not found.
:http:statuscode:`501 Not implemented`:
@@ -1117,6 +1185,10 @@ Cashouts
Response is a `Cashouts`.
:http:statuscode:`204 No Content`:
No cash-out operations were found.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
@@ -1163,6 +1235,10 @@ Cashouts
Response is a `GlobalCashouts`.
:http:statuscode:`204 No Content`:
No cash-out operations were found.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
@@ -1192,12 +1268,16 @@ Cashouts
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.
+
**Response:**
:http:statuscode:`200 OK`:
The TAN code have been sent. This returns `TanTransmission` response.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not Found`:
The challenge was not found.
:http:statuscode:`502 Bad Gateway`:
@@ -1236,6 +1316,8 @@ Cashouts
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.
+
+ This endpoints is not authenticated for token creation challenges. Too many unsuccessful attempts to confirm token creation challenges block the account.
**Request:**
@@ -1251,7 +1333,9 @@ Cashouts
:http:statuscode:`204 No Content`:
The challenge is confirmed.
:http:statuscode:`401 Unauthorized`:
- Invalid credentials or missing rights.
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
:http:statuscode:`404 Not Found`:
The challenge was not found.
:http:statuscode:`409 Conflict`:
@@ -1303,6 +1387,10 @@ Monitor
The bank responds with `MonitorResponse`.
:http:statuscode:`400 Bad Request`:
This error may indicate that the *which* parameter is not appropriate for the selected *timeframe*. For example, timeframe=month and which=20 would result in this error.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
**Details:**
