docs: add precisions on auth for apps (#10368)

Co-authored-by: Raphaël Odini <[email protected]>
Co-authored-by: Alex Garel <[email protected]>

docs/api/index.md

@@ -74,23 +74,29 @@ While testing your applications, **make all API requests to the staging environm
 
 ## Authentication
 
-We ask you to **always use a custom User-Agent to identify you** (to not risk being identified as a bot). The User-Agent should be in the form of `AppName/Version (ContactEmail)`. For example,
+We ask you to **always use a custom User-Agent to identify your app** (to not risk being identified as a bot). The User-Agent should be in the form of `AppName/Version (ContactEmail)`. For example,
 `MyApp/1.0 ([email protected])`.
 
 - READ operations (getting info about a product, etc...) do not require authentication other than the custom User-Agent.
-
 - WRITE operations (Editing an Existing Product, Uploading images…) **require authentication**. We do this as another layer of protection against spam.
 
-Create an account on the [Open Food Facts app](https://world.openfoodfacts.org/). From there, you have two options:
+Create an account on the [Open Food Facts app](https://world.openfoodfacts.org/) for your app (and notify [email protected] of the account name, so that we grant it special app privileges). From there, you have two options:
 
 - **The preferred one**:
   Use the login API to get a session cookie and use this cookie for authentication in your subsequent requests. However, the session must always be used from the same IP address, and there's a limit on sessions per user (currently 10) with older sessions being automatically logged out to stay within the limit.
 - If session conditions are too restrictive for your use case, include your account credentials as parameters for authenticated requests where `user_id` is your username and `password` is your password (do this on POST / PUT / DELETE requests, not on GET).
 
 You can create a global account to allow your app users to contribute without registering individual accounts on the Open Food Facts website. This way, we know that these contributions came from your application.
 
+We however ask that you send the [`app_name`, `app_version` and `app_uuid` parameters](https://openfoodfacts.github.io/openfoodfacts-server/api/ref-v2/#post-/cgi/product_jqm2.pl) in your write queries. 
+* `app_name=MyApp` 
+* `app_version=1.1` 
+* `app_uuid=xxxx`: a salted random uuid for the user so that Open Food Facts moderators can selectively ban any problematic user without banning your whole app account.
+
 > Production and staging have different account databases, so **the account you create in the production environment will only work for production requests**. If you want to query (WRITE requests) the staging environment, you'll need to create another account there too.
 
+> Note: we're currently moving to a modern Auth system (Keycloak), so we will have new Auth options, hopefully this year.
+
 ## Reference Documentation (OpenAPI)
 
 We are building a complete OpenAPI reference. Here is a list of the current API documentation available:

docs/api/ref/api.yml

@@ -221,21 +221,21 @@ paths:
           content:
             application/json:
               schema:
-                AllOf:
-                  - $ref: ./responses/add_or_edit_a_product.yaml
-                  - $ref: ./responses/change_ref_properties.yaml
+                $ref: ./responses/add_or_edit_a_product.yaml
       parameters: []
       requestBody:
         content:
           multipart/form-data:
             schema:
-              AllOf:
+              allOf:
                 - $ref: ./requestBodies/add_or_edit_a_product.yaml
                 - $ref: ./requestBodies/change_ref_properties.yaml
       tags:
         - Write Requests
       description: |
-        If the barcode exists then you will be editing the existing product,
+        This updates a product.
+
+        Note: If the barcode exists then you will be editing the existing product,
         However if it doesn''t you will be creating a new product with that unique barcode,
         and adding properties to the product.
   /api/v2/search:

docs/api/ref/requestBodies/change_ref_properties.yaml

@@ -21,10 +21,12 @@ properties:
       When an app uses a single user to log its contributions,
       it might be interesting to know which user of the app is providing the information.
       You can use this field to provide an identifier (eg: an sha1 of the username) that's privacy preserving. Make sure that your salt is strong, perfectly random and secret
+
+      In case we have trouble with one of your user, it helps our moderators revert edits.
   User-Agent:
     type: string
     description: |
       It is required that you pass a specific User-Agent header when you do an API request.
       But some times it's not possible to modify such a header
       (eg. request using JavaScript in a browser).
-      In such cases, you can override it with this parameter.
+      In such cases, you can override it with this parameter.