taler-docs

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

post-private-fountains.rst (3038B)

      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`` (see :ref:`Scopes <merchant-api-scopes>`)
     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     The latter is returned with
     27     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_TOKEN_FAMILY_SLUG_UNKNOWN``.
     28   :http:statuscode:`500 Internal Server Error`:
     29     The server experienced an internal failure.
     30 
     31   **Details:**
     32 
     33   .. ts:def:: FountainCreateRequest
     34 
     35     interface FountainCreateRequest {
     36 
     37       // Human-readable description; preferably an opaque campaign
     38       // or recipient identifier from the institution's system.
     39       // The merchant backend does not need -- and should not
     40       // receive -- the user's real identity.
     41       description: string;
     42 
     43       // How often wallets holding this fountain's secret should
     44       // re-poll ``GET /fountain/info`` for updated grants.
     45       poll_freq: RelativeTime;
     46 
     47       // One grant per token family the user may withdraw
     48       // tokens for. May be empty; grants can be added later.
     49       grants: FountainGrant[];
     50     }
     51 
     52   .. ts:def:: FountainGrant
     53 
     54     interface FountainGrant {
     55 
     56       // Slug of the token family this grant refers to.
     57       token_family_slug: Slug;
     58 
     59       // Maximum number of tokens the fountain will blind-sign
     60       // per key validity period for this family.
     61       tokens_per_period_limit: Integer;
     62 
     63       // Number of tokens the wallet should aim to hold per period
     64       // (client-side stocking target; must not exceed
     65       // ``tokens_per_period_limit``).
     66       tokens_per_period_stash: Integer;
     67 
     68       // Number of key slots ahead of the current one the wallet
     69       // may withdraw tokens for. Bounds prefetching and the time
     70       // for which already-withdrawn promotional tokens remain usable.
     71       // Must be between 0 and 12 inclusive; 0 allows only the current slot.
     72       key_window_size: Integer;
     73     }
     74 
     75   .. ts:def:: FountainCreateResponse
     76 
     77     interface FountainCreateResponse {
     78 
     79       // Identifier of the fountain, used for subsequent CRUD
     80       // operations and included in the wallet onboarding URI.
     81       fountain_id: Slug;
     82 
     83       // 256-bit bearer credential for the wallet, Crockford
     84       // Base32 encoded. Returned exactly once; the backend
     85       // stores only a hash of it.
     86       fountain_secret: string;
     87     }