commit 6d429fbe7b038f64c62652de3807c80ea845e289
parent 0cb6b9d4878f4acc45e833ec8abbfaaf58b99d03
Author: Antoine A <>
Date: Thu, 13 Jun 2024 11:19:03 +0200
update token API
Diffstat:
2 files changed, 105 insertions(+), 40 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -49,7 +49,7 @@ client to authenticate as the admin.
.. http:post:: /accounts/$USERNAME/token
- Create or refresh an authentification token.
+ Create an authentification token.
**Request:**
@@ -68,7 +68,7 @@ client to authenticate as the admin.
// access if they are refreshed in time.
refreshable?: boolean;
- // Token description
+ // Optional token description
// @since v4
description?: string;
}
@@ -147,11 +147,14 @@ client to authenticate as the admin.
// access if they are refreshed in time.
refreshable: boolean;
- // Token description
+ // Optional token description
description?: string;
// Time when the token was last used.
last_access: Timestamp;
+
+ // Opaque unique ID used for pagination.
+ row_id: Integer;
}
Bank Web UI
diff --git a/design-documents/049-auth.rst b/design-documents/049-auth.rst
@@ -33,56 +33,59 @@ Proposed Solution
We define a ``token`` endpoint that can be used to obtain access tokens from
other forms of authentication, typically HTTP Basic auth.
-
-.. _dd48-token:
-
-Token Endpoint
+Token Creation
--------------
.. http:post:: /${RESOURCE...}/token
- **Request Body**
+ Create an authentification token.
+
+ **Request:**
- .. ts:def:: TokenRequest
+ .. ts:def:: TokenRequest
- interface TokenRequest {
- // Service-defined scope for the token.
- // Typical scopes would be "readonly" or "readwrite".
- scope: string;
+ interface TokenRequest {
+ // Service-defined scope for the token.
+ // Typical scopes would be "readonly" or "readwrite".
+ scope: string;
- // Server may impose its own upper bound
- // on the token validity duration
- duration?: RelativeTime;
+ // Server may impose its own upper bound
+ // on the token validity duration
+ duration?: RelativeTime;
- // Is the token refreshable into a new token during its
- // validity?
- // Refreshable tokens effectively provide indefinite
- // access if they are refreshed in time.
- refreshable?: boolean;
- }
+ // Is the token refreshable into a new token during its
+ // validity?
+ // Refreshable tokens effectively provide indefinite
+ // access if they are refreshed in time.
+ refreshable?: boolean;
- **Response:**
+ // Optional token description
+ // @since v4
+ description?: string;
+ }
- :http:statuscode:`200 Ok`:
- The response is a `TokenSuccessResponse`
+ **Response:**
- **Details:**
+ :http:statuscode:`200 Ok`:
+ The response is a `TokenSuccessResponse`
- .. ts:def:: TokenSuccessResponse
+ **Details:**
- interface TokenSuccessResponse {
- // Expiration determined by the server.
- // Can be based on the token_duration
- // from the request, but ultimately the
- // server decides the expiration.
- expiration: Timestamp;
+ .. ts:def:: TokenSuccessResponse
- // Opque access token.
- access_token: string;
- }
+ interface TokenSuccessResponse {
+ // Expiration determined by the server.
+ // Can be based on the token_duration
+ // from the request, but ultimately the
+ // server decides the expiration.
+ expiration: Timestamp;
+
+ // Opque access token.
+ access_token: string;
+ }
Token Revocation
------------------
+----------------
Clients using session tokens log by forgetting the session token.
Tokens can be explicitly revoked by making a ``DELETE`` request on
@@ -90,12 +93,71 @@ the token endpoint.
.. http:delete:: /${RESOURCE...}/token
- Invalidate the access token that is being used to make the request.
+ Invalidate the access token that is being used to make the request.
+
+ **Authentication:** The client must authenticate
+ with a valid access token.
+
+Token Information
+-----------------
+
+List existing token informations.
+
+.. http:get:: /${RESOURCE...}/tokens
+
+ **Request:**
+
+ :query delta: *Optional.*
+ Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
+ :query start: *Optional.*
+ Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Response is a `TokenInfos`.
+ :http:statuscode:`204 No content`:
+ No tokens.
+
+ **Details:**
+
+ .. ts:def:: TokenInfos
+
+ interface TokenInfos {
+ tokens: TokenInfo[];
+ }
+
+ .. ts:def:: TokenInfo
+
+ interface TokenInfo {
+ // Time when the token was created.
+ creation_time: Timestamp;
+
+ // Expiration determined by the server.
+ // Can be based on the token_duration
+ // from the request, but ultimately the
+ // server decides the expiration.
+ expiration: Timestamp;
+
+ // Service-defined scope for the token.
+ // Typical scopes would be "readonly" or "readwrite".
+ scope: string;
+
+ // Is the token refreshable into a new token during its
+ // validity?
+ // Refreshable tokens effectively provide indefinite
+ // access if they are refreshed in time.
+ refreshable: boolean;
- **Authentication:** The client must authenticate
- with a valid access token.
+ // Optional token description
+ description?: string;
+ // Time when the token was last used.
+ last_access: Timestamp;
+ // Opaque unique ID used for pagination.
+ row_id: Integer;
+ }
Definition of Done
==================
