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 ```