taler-docs

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

post-management-instances-INSTANCE-auth.rst (4346B)

      1 .. http:post:: /management/instances/$INSTANCE/auth
      2 .. http:post:: [/instances/$INSTANCE]/private/auth
      3 
      4   Update the authentication settings for an instance.  POST operations against
      5   an instance are authenticated by checking that an authorization is provided
      6   that matches either the credential required by the instance being modified
      7   OR the ``admin`` instance, depending on the access path used.
      8 
      9   **Required permission:** ``auth-write`` on the ``/private`` path,
     10   ``instances-auth-write`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`)
     11 
     12   **Request:** Requests to ``/management/instances/$INSTANCE/auth`` use an
     13   `InstanceAuthConfigurationMessage`.  Requests to the instance's own
     14   ``/private/auth`` endpoint use an `InstanceAuthChangeRequest` and must
     15   reauthenticate with the current password whenever the existing
     16   authentication method is ``token``.  If ``PASSWORD_CHANGE_MFA`` is enabled,
     17   the merchant must additionally solve one usable challenge from the channels
     18   listed in ``MANDATORY_TAN_CHANNELS``.  When several channels are available,
     19   they are returned with ``combi_and`` set to false so the merchant may choose
     20   any one of them.
     21 
     22   **Response:**
     23 
     24   :http:statuscode:`202 Accepted`:
     25     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v21**
     26   :http:statuscode:`204 No content`:
     27     The backend has successfully changed the credentials for the instance.
     28   :http:statuscode:`401 Unauthorized`:
     29     The request is unauthorized.  A missing or incorrect ``old_password`` on
     30     the ``/private`` path is returned with
     31     ``TALER_EC_MERCHANT_PRIVATE_POST_INSTANCE_AUTH_BAD_OLD_PASSWORD``.
     32   :http:statuscode:`403 Forbidden`:
     33     ``PASSWORD_CHANGE_MFA`` is enabled, but no configured MFA channel is
     34     available for this instance.
     35     Returned with ``TALER_EC_MERCHANT_GENERIC_MFA_MISSING``.
     36   :http:statuscode:`404 Not found`:
     37     This instance is unknown and thus cannot be reconfigured.
     38     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
     39   :http:statuscode:`413 Request entity too large`:
     40     The uploaded body is to long, it exceeds the size limit.
     41     Returned with an error code of
     42     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     43   :http:statuscode:`500 Internal Server Error`:
     44     The server experienced an internal failure.
     45     Returned with ``TALER_EC_GENERIC_DB_START_FAILED``,
     46     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     47     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``.
     48 
     49   **Details:**
     50 
     51   .. ts:def:: InstanceAuthConfigurationMessage
     52 
     53     type InstanceAuthConfigurationMessage = InstanceAuthConfigToken | InstanceAuthConfigTokenOLD | InstanceAuthConfigExternal
     54 
     55   .. ts:def:: InstanceAuthChangeRequest
     56 
     57     // @since **v40**
     58     type InstanceAuthChangeRequest = InstanceAuthConfigurationMessage & {
     59       // Required on the instance's own /private/auth endpoint when the
     60       // current authentication method is "token".  It is checked by the
     61       // backend against the stored password before the update is committed.
     62       // Administrative changes through /management do not use this field.
     63       old_password: string;
     64     };
     65 
     66   .. ts:def:: InstanceAuthConfigToken
     67 
     68     // @since **v19**
     69     interface InstanceAuthConfigToken {
     70       // The API is accessible through API tokens.
     71       // Tokens are retrieved from the /private/token
     72       // endpoint.
     73       method: "token";
     74 
     75       // Authentication against the /private/token endpoint
     76       // is done using basic authentication with the configured password
     77       // in the "password" field. Tokens are passed to other endpoints for
     78       // authorization using RFC 8959 bearer tokens.
     79       password: string;
     80 
     81     }
     82 
     83   .. ts:def:: InstanceAuthConfigTokenOLD
     84 
     85     // @deprecated since **v19**
     86     interface InstanceAuthConfigTokenOLD {
     87       // The API is accessible through API tokens.
     88       // Tokens are retrieved from the /private/token
     89       // endpoint.
     90       method: "token";
     91 
     92       // The value of this field MUST begin with the string "secret-token:".
     93       token: string;
     94 
     95     }
     96 
     97   .. ts:def:: InstanceAuthConfigExternal
     98 
     99     // @deprecated since **v20**
    100     interface InstanceAuthConfigExternal {
    101       // The mechant backend does not do
    102       // any authentication checks.  Instead an API
    103       // gateway must do the authentication.
    104       method: "external";
    105     }