taler-docs

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

post-private-token.rst (2927B)

      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:`400 Bad Request`:
     27     The request body is malformed.
     28     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     29   :http:statuscode:`403 Forbidden`:
     30     The provided token has insufficient permissions for the requested scope.
     31     Returned with ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
     32   :http:statuscode:`413 Request entity too large`:
     33     The uploaded body is to long, it exceeds the size limit.
     34     Returned with an error code of
     35     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     36   :http:statuscode:`500 Internal Server Error`:
     37     The server experienced an internal failure.
     38     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     39 
     40   **Details:**
     41 
     42   .. ts:def:: LoginTokenRequest
     43 
     44     interface LoginTokenRequest {
     45       // Scope of the token (which kinds of operations it will allow)
     46       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     47 
     48       // Server may impose its own upper bound
     49       // on the token validity duration
     50       duration?: RelativeTime;
     51 
     52       // Optional token description
     53       description?: string;
     54 
     55       // Can this token be refreshed?
     56       // Defaults to false. Deprecated since **v19**.
     57       // Use ":refreshable" scope prefix instead.
     58       refreshable?: boolean;
     59     }
     60 
     61   .. ts:def:: LoginTokenSuccessResponse
     62 
     63     interface LoginTokenSuccessResponse {
     64       // deprecated since v19. See access_token
     65       token: string;
     66 
     67       // The login token that can be used to access resources
     68       // that are in scope for some time. Must be prefixed
     69       // with "Bearer " when used in the "Authorization" HTTP header.
     70       // Will already begin with the RFC 8959 prefix.
     71       // **Since v19**
     72       access_token: string;
     73 
     74       // Scope of the token (which kinds of operations it will allow)
     75       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
     76 
     77       // Server may impose its own upper bound
     78       // on the token validity duration
     79       expiration: Timestamp;
     80 
     81       // Can this token be refreshed?
     82       refreshable: boolean;
     83     }