taler-docs

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

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

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