Contents

POST /accounts/$USERNAME/token#

Create or refresh an authentication token.

With HTTP Basic authentication, this endpoint creates a token from the account password. With bearer authentication, the presented token must be refreshable and the endpoint rotates it into a newly generated token. A refreshed token cannot have a broader scope than its source token.

Request:

interface TokenRequest {
  // Scope for the token.
  scope: "readonly" | "readwrite" | "revenue" | "wiregateway" | "observability";

  // Custom 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;

  // Optional token description
  // @since **v4**
  description?: string;
}

Response:

200 Ok:

Response is a TokenSuccessResponse.

202 Accepted:

2FA is required for this operation. This returns the ChallengeResponse response. @since v10

401 Unauthorized:

Invalid or missing credentials.

403 Forbidden:

  • TALER_EC_GENERIC_FORBIDDEN: missing rights.

  • TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT: the source token is not refreshable or the requested scope is broader than its scope.

  • TALER_EC_BANK_ACCOUNT_LOCKED: account is locked and cannot create new token using its password.

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;

  // Opque access token.
  access_token: string;
}

Refresh rotation:

A successful bearer-authenticated refresh atomically creates the replacement token and limits the source token’s expiration to the earlier of its existing expiration and five minutes after the first successful refresh. This is a fixed, non-sliding overlap period: later refresh retries never extend the source token’s new deadline. The source token remains usable until that deadline so that a client can retry after losing a successful response.

A retry during the overlap period may create another valid replacement. Clients must therefore treat each successful response as a fresh credential, persist it atomically and tolerate multiple replacement tokens. After the source token expires, it can no longer authenticate or be refreshed.

Contents