taler-docs

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

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

      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** the request must be an `InstanceAuthConfigurationMessage`.
     13 
     14   **Response:**
     15 
     16   :http:statuscode:`202 Accepted`:
     17     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v21**
     18   :http:statuscode:`204 No content`:
     19     The backend has successfully changed the credentials for the instance.
     20   :http:statuscode:`401 Unauthorized`:
     21     The request is unauthorized.
     22   :http:statuscode:`403 Forbidden`:
     23     MFA channels are not available for this instance.
     24     Returned with ``TALER_EC_MERCHANT_GENERIC_MFA_MISSING``.
     25   :http:statuscode:`404 Not found`:
     26     This instance is unknown and thus cannot be reconfigured.
     27     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
     28   :http:statuscode:`413 Request entity too large`:
     29     The uploaded body is to long, it exceeds the size limit.
     30     Returned with an error code of
     31     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     32   :http:statuscode:`500 Internal Server Error`:
     33     The server experienced an internal failure.
     34     Returned with ``TALER_EC_GENERIC_DB_START_FAILED``,
     35     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     36     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``.
     37 
     38   **Details:**
     39 
     40   .. ts:def:: InstanceAuthConfigurationMessage
     41 
     42     type InstanceAuthConfigurationMessage = InstanceAuthConfigToken | InstanceAuthConfigTokenOLD | InstanceAuthConfigExternal
     43 
     44   .. ts:def:: InstanceAuthConfigToken
     45 
     46     // @since **v19**
     47     interface InstanceAuthConfigToken {
     48       // The API is accessible through API tokens.
     49       // Tokens are retrieved from the /private/token
     50       // endpoint.
     51       method: "token";
     52 
     53       // Authentication against the /private/token endpoint
     54       // is done using basic authentication with the configured password
     55       // in the "password" field. Tokens are passed to other endpoints for
     56       // authorization using RFC 8959 bearer tokens.
     57       password: string;
     58 
     59     }
     60 
     61   .. ts:def:: InstanceAuthConfigTokenOLD
     62 
     63     // @deprecated since **v19**
     64     interface InstanceAuthConfigTokenOLD {
     65       // The API is accessible through API tokens.
     66       // Tokens are retrieved from the /private/token
     67       // endpoint.
     68       method: "token";
     69 
     70       // The value of this field MUST begin with the string "secret-token:".
     71       token: string;
     72 
     73     }
     74 
     75   .. ts:def:: InstanceAuthConfigExternal
     76 
     77     // @deprecated since **v20**
     78     interface InstanceAuthConfigExternal {
     79       // The mechant backend does not do
     80       // any authentication checks.  Instead an API
     81       // gateway must do the authentication.
     82       method: "external";
     83     }