taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-private-token.rst (2417B)

      1 .. http:post:: [/instances/$INSTANCE]/private/token
      2 
      3   Retrieve an access token for the merchant API for instance
      4   ``$INSTANCE``.
      5   When accessed with a Bearer token for authentication, the token
      6   must have scope ``token-refresh`` and the requested scope must be a subset
      7   of the scope of the token.
      8   When accessed with Basic authentication the instance password must be provided
      9   along with ``$INSTANCE`` as username.
     10 
     11 
     12   **Required permission:** ``token-refresh`` if accessed using a Bearer token.
     13 
     14   **Request:**
     15 
     16   The request must be a `LoginTokenRequest`.
     17 
     18   **Response:**
     19 
     20   :http:statuscode:`200 Ok`:
     21     The backend is returning the access token in a
     22     `LoginTokenSuccessResponse`.
     23   :http:statuscode:`202 Accepted`:
     24     2FA is required for this operation.
     25     This returns the `ChallengeResponse`. @since **v21**
     26   :http:statuscode:`500 Internal Server Error`:
     27     The server experienced an internal failure.
     28     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     29 
     30   **Details:**
     31 
     32   .. ts:def:: LoginTokenRequest
     33 
     34     interface LoginTokenRequest {
     35       // Scope of the token (which kinds of operations it will allow)
     36       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     37 
     38       // Server may impose its own upper bound
     39       // on the token validity duration
     40       duration?: RelativeTime;
     41 
     42       // Optional token description
     43       description?: string;
     44 
     45       // Can this token be refreshed?
     46       // Defaults to false. Deprecated since **v19**.
     47       // Use ":refreshable" scope prefix instead.
     48       refreshable?: boolean;
     49     }
     50 
     51   .. ts:def:: LoginTokenSuccessResponse
     52 
     53     interface LoginTokenSuccessResponse {
     54       // deprecated since v19. See access_token
     55       token: string;
     56 
     57       // The login token that can be used to access resources
     58       // that are in scope for some time. Must be prefixed
     59       // with "Bearer " when used in the "Authorization" HTTP header.
     60       // Will already begin with the RFC 8959 prefix.
     61       // **Since v19**
     62       access_token: string;
     63 
     64       // Scope of the token (which kinds of operations it will allow)
     65       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     66 
     67       // Server may impose its own upper bound
     68       // on the token validity duration
     69       expiration: Timestamp;
     70 
     71       // Can this token be refreshed?
     72       refreshable: boolean;
     73     }