taler-docs

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

post-private-token.rst (2265B)

      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 
     27   **Details:**
     28 
     29   .. ts:def:: LoginTokenRequest
     30 
     31     interface LoginTokenRequest {
     32       // Scope of the token (which kinds of operations it will allow)
     33       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     34 
     35       // Server may impose its own upper bound
     36       // on the token validity duration
     37       duration?: RelativeTime;
     38 
     39       // Optional token description
     40       description?: string;
     41 
     42       // Can this token be refreshed?
     43       // Defaults to false. Deprecated since **v19**.
     44       // Use ":refreshable" scope prefix instead.
     45       refreshable?: boolean;
     46     }
     47 
     48   .. ts:def:: LoginTokenSuccessResponse
     49 
     50     interface LoginTokenSuccessResponse {
     51       // deprecated since v19. See access_token
     52       token: string;
     53 
     54       // The login token that can be used to access resources
     55       // that are in scope for some time. Must be prefixed
     56       // with "Bearer " when used in the "Authorization" HTTP header.
     57       // Will already begin with the RFC 8959 prefix.
     58       // **Since v19**
     59       access_token: string;
     60 
     61       // Scope of the token (which kinds of operations it will allow)
     62       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     63 
     64       // Server may impose its own upper bound
     65       // on the token validity duration
     66       expiration: Timestamp;
     67 
     68       // Can this token be refreshed?
     69       refreshable: boolean;
     70     }