taler-docs

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

post-private-fountains.rst (2777B)

      1 .. http:post:: [/instances/$INSTANCE]/private/fountains
      2 
      3   This is used to create a fountain: a bearer credential that
      4   entitles a wallet to withdraw blind-signed promotional tokens for
      5   a set of token families
      6   (see :doc:`DD 98 </design-documents/098-token-fountains>`).
      7   This endpoint is available since protocol **vTokenFountains**.
      8 
      9   **Required permission:** ``fountains-write``
     10 
     11   **Request:**
     12 
     13   The request must be a `FountainCreateRequest`.
     14 
     15   **Response:**
     16 
     17   :http:statuscode:`200 OK`:
     18     The fountain was created successfully.
     19     Returns a `FountainCreateResponse`.
     20   :http:statuscode:`400 Bad Request`:
     21     The request body is malformed.
     22     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     23   :http:statuscode:`404 Not found`:
     24     The merchant instance is unknown, or a ``token_family_slug``
     25     in the grants does not refer to a known token family.
     26   :http:statuscode:`500 Internal Server Error`:
     27     The server experienced an internal failure.
     28 
     29   **Details:**
     30 
     31   .. ts:def:: FountainCreateRequest
     32 
     33     interface FountainCreateRequest {
     34 
     35       // Human-readable description; preferably an opaque campaign
     36       // or recipient identifier from the institution's system.
     37       // The merchant backend does not need -- and should not
     38       // receive -- the user's real identity.
     39       description: string;
     40 
     41       // How often wallets holding this fountain's secret should
     42       // re-poll ``GET /fountain/info`` for updated grants.
     43       poll_freq: RelativeTime;
     44 
     45       // One grant per token family the user may withdraw
     46       // tokens for.
     47       grants: FountainGrant[];
     48     }
     49 
     50   .. ts:def:: FountainGrant
     51 
     52     interface FountainGrant {
     53 
     54       // Slug of the token family this grant refers to.
     55       token_family_slug: string;
     56 
     57       // Maximum number of tokens the fountain will blind-sign
     58       // per key validity period for this family.
     59       tokens_per_period_limit: Integer;
     60 
     61       // Number of tokens the wallet should aim to hold per period
     62       // (client-side stocking target; must not exceed
     63       // ``tokens_per_period_limit``).
     64       tokens_per_period_stash: Integer;
     65 
     66       // Number of key slots ahead of the current one the wallet
     67       // may withdraw tokens for. Bounds prefetching and the time
     68       // for which already-withdrawn promotional tokens remain usable.
     69       key_window_size: Integer;
     70     }
     71 
     72   .. ts:def:: FountainCreateResponse
     73 
     74     interface FountainCreateResponse {
     75 
     76       // Identifier of the fountain, used for subsequent CRUD
     77       // operations and included in the wallet onboarding URI.
     78       fountain_id: string;
     79 
     80       // 256-bit bearer credential for the wallet, Crockford
     81       // Base32 encoded. Returned exactly once; the backend
     82       // stores only a hash of it.
     83       fountain_secret: string;
     84     }