github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/user-action-required.md (about)

     1  [Table of contents](README.md#table-of-contents)
     2  
     3  # User action is required
     4  
     5  This document explains how the stack can alert applications that an user action
     6  is required to perform the expected services. For example, the stack can block
     7  most of its API until the user read and sign new terms of services.
     8  
     9  ## HTTP 402 Error
    10  
    11  In some cases the stack will return a 402 error to API requests. 402 will be
    12  used to denote error that require an user's action.
    13  
    14  For now, the only use cases are a Terms Of Services update. But some other use
    15  cases might appear in the future. The specific cause of this error will be
    16  provided within the body of the response (see examples below).
    17  
    18  ```http
    19  HTTP/1.1 402 Payment Required
    20  Content-Length: ...
    21  Content-Type: application/vnd.api+json
    22  ```
    23  
    24  ```json
    25  {
    26      "errors": [
    27          {
    28              "status": "402",
    29              "title": "TOS Updated",
    30              "code": "tos-updated",
    31              "detail": "Terms of services have been updated",
    32              "links": {
    33                  "self": "https://manager.cozycloud.cc/cozy/tos?domain=..."
    34              }
    35          }
    36      ]
    37  }
    38  ```
    39  
    40  If they receive such a code, the clients should block any further action on the
    41  stack, warn the user with the necessary message and provide a button allowing
    42  the user to perform the required action.
    43  
    44  -   If the client knows the specific `error` code, display a beautiful message.
    45  -   Otherwise, display the message provided by the stack and use the
    46      links.action on the button.
    47  
    48  Possible other codes in the future: `payment_required` for functions requiring a
    49  premium account, etc.
    50  
    51  ## HTTP 410 error
    52  
    53  The 410 HTTP error code will be used when an instance has been moved to a new
    54  address.
    55  
    56  ```json
    57  {
    58      "errors": [
    59          {
    60              "status": "410",
    61              "title": "Cozy has been moved",
    62              "code": "moved",
    63              "detail": "The Cozy has been moved to a new address",
    64              "links": {
    65                  "related": "https://newcozy.example.org/"
    66              }
    67          }
    68      ]
    69  }
    70  ```
    71  
    72  # Anticipating these errors and warning the user
    73  
    74  An enpoints exists to get the list of warnings that the user can anticipate. For
    75  applications these warnings are included directly into the HTML of the index
    76  page, as follow:
    77  
    78  ```html
    79  <meta name="user-action-required"
    80    data-title="{{ .Title }}"
    81    data-code="{{ .Code }}"
    82    data-detail="{{ .Detail }}"
    83    data-links="{{ .Links.Self }}"} />
    84  ```
    85  
    86  ## Request
    87  
    88  ```http
    89  GET /settings/warnings HTTP/1.1
    90  ```
    91  
    92  ## Response
    93  
    94  ```http
    95  HTTP/1.1 402 Payment Required
    96  Content-Length: ...
    97  Content-Type: application/vnd.api+json
    98  ```
    99  
   100  ```json
   101  {
   102      "errors": [
   103          {
   104              "status": "402",
   105              "title": "TOS Updated",
   106              "code": "tos-updated",
   107              "detail": "Terms of services have been updated",
   108              "links": {
   109                  "self": "https://manager.cozycloud.cc/cozy/tos?domain=..."
   110              }
   111          }
   112      ]
   113  }
   114  ```