post-accounts-USERNAME-token.rst (2743B)
1 .. http:post:: /accounts/$USERNAME/token 2 3 Create or refresh an authentication token. 4 5 With HTTP Basic authentication, this endpoint creates a token from the 6 account password. With bearer authentication, the presented token must be 7 refreshable and the endpoint rotates it into a newly generated token. A 8 refreshed token cannot have a broader scope than its source token. 9 10 **Request:** 11 12 .. ts:def:: TokenRequest 13 14 interface TokenRequest { 15 // Scope for the token. 16 scope: "readonly" | "readwrite" | "revenue" | "wiregateway" | "observability"; 17 18 // Custom token validity duration 19 duration?: RelativeTime; 20 21 // Is the token refreshable into a new token during its 22 // validity? 23 // Refreshable tokens effectively provide indefinite 24 // access if they are refreshed in time. 25 refreshable?: boolean; 26 27 // Optional token description 28 // @since **v4** 29 description?: string; 30 } 31 32 **Response:** 33 34 :http:statuscode:`200 Ok`: 35 Response is a `TokenSuccessResponse`. 36 :http:statuscode:`202 Accepted`: 37 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10** 38 :http:statuscode:`401 Unauthorized`: 39 Invalid or missing credentials. 40 :http:statuscode:`403 Forbidden`: 41 * ``TALER_EC_GENERIC_FORBIDDEN``: missing rights. 42 * ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``: the source token is not refreshable or the requested scope is broader than its scope. 43 * ``TALER_EC_BANK_ACCOUNT_LOCKED``: account is locked and cannot create new token using its password. 44 45 **Details:** 46 47 .. ts:def:: TokenSuccessResponse 48 49 interface TokenSuccessResponse { 50 // Expiration determined by the server. 51 // Can be based on the token_duration 52 // from the request, but ultimately the 53 // server decides the expiration. 54 expiration: Timestamp; 55 56 // Opque access token. 57 access_token: string; 58 } 59 60 **Refresh rotation:** 61 62 A successful bearer-authenticated refresh atomically creates the replacement 63 token and limits the source token's expiration to the earlier of its existing 64 expiration and five minutes after the first successful refresh. This is a 65 fixed, non-sliding overlap period: later refresh retries never extend the 66 source token's new deadline. The source token remains usable until that 67 deadline so that a client can retry after losing a successful response. 68 69 A retry during the overlap period may create another valid replacement. 70 Clients must therefore treat each successful response as a fresh credential, 71 persist it atomically and tolerate multiple replacement tokens. After the 72 source token expires, it can no longer authenticate or be refreshed.