POST [/instances/$INSTANCE]/private/token

Retrieve an access token for the merchant API for instance $INSTANCE. When accessed with a Bearer token for authentication, the token must have scope token-refresh and the requested scope must be a subset of the scope of the token. When accessed with Basic authentication the instance password must be provided along with $INSTANCE as username.

Required permission: token-refresh if accessed using a Bearer token.

Request:

The request must be a LoginTokenRequest.

Response:

200 Ok:

The backend is returning the access token in a LoginTokenSuccessResponse.

202 Accepted:

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

400 Bad Request:

The request body is malformed. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED.

403 Forbidden:

The provided token has insufficient permissions for the requested scope. Returned with TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

500 Internal Server Error:

The server experienced an internal failure. Returned with TALER_EC_GENERIC_DB_STORE_FAILED.

Details:

interface LoginTokenRequest {
  // Scope of the token (which kinds of operations it will allow)
  scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";

  // Server may impose its own upper bound
  // on the token validity duration
  duration?: RelativeTime;

  // Optional token description
  description?: string;

  // Can this token be refreshed?
  // Defaults to false. Deprecated since **v19**.
  // Use ":refreshable" scope suffix instead.
  refreshable?: boolean;
}

interface LoginTokenSuccessResponse {
  // deprecated since v19. See access_token
  token: string;

  // The login token that can be used to access resources
  // that are in scope for some time. Must be prefixed
  // with "Bearer " when used in the "Authorization" HTTP header.
  // Will already begin with the RFC 8959 prefix.
  // **Since v19**
  access_token: string;

  // Scope of the token (which kinds of operations it will allow)
  scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";

  // Server may impose its own upper bound
  // on the token validity duration
  expiration: Timestamp;

  // Can this token be refreshed?
  refreshable: boolean;
}