taler-docs

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

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

      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     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
     27   :http:statuscode:`413 Request entity too large`:
     28     The uploaded body is to long, it exceeds the size limit.
     29     Returned with an error code of
     30     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     31   :http:statuscode:`500 Internal Server Error`:
     32     The server experienced an internal failure.
     33     Returned with ``TALER_EC_GENERIC_DB_START_FAILED``,
     34     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     35     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: InstanceAuthConfigurationMessage
     40 
     41     type InstanceAuthConfigurationMessage = InstanceAuthConfigToken | InstanceAuthConfigTokenOLD | InstanceAuthConfigExternal
     42 
     43   .. ts:def:: InstanceAuthConfigToken
     44 
     45     // @since **v19**
     46     interface InstanceAuthConfigToken {
     47       // The API is accessible through API tokens.
     48       // Tokens are retrieved from the /private/token
     49       // endpoint.
     50       method: "token";
     51 
     52       // Authentication against the /private/token endpoint
     53       // is done using basic authentication with the configured password
     54       // in the "password" field. Tokens are passed to other endpoints for
     55       // authorization using RFC 8959 bearer tokens.
     56       password: string;
     57 
     58     }
     59 
     60   .. ts:def:: InstanceAuthConfigTokenOLD
     61 
     62     // @deprecated since **v19**
     63     interface InstanceAuthConfigTokenOLD {
     64       // The API is accessible through API tokens.
     65       // Tokens are retrieved from the /private/token
     66       // endpoint.
     67       method: "token";
     68 
     69       // The value of this field MUST begin with the string "secret-token:".
     70       token: string;
     71 
     72     }
     73 
     74   .. ts:def:: InstanceAuthConfigExternal
     75 
     76     // @deprecated since **v20**
     77     interface InstanceAuthConfigExternal {
     78       // The mechant backend does not do
     79       // any authentication checks.  Instead an API
     80       // gateway must do the authentication.
     81       method: "external";
     82     }