github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/settings.md (about) 1 [Table of contents](README.md#table-of-contents) 2 3 # Settings 4 5 ## Disk usage 6 7 8 ### GET /settings/disk-usage 9 10 Says how many bytes are available and used to store files. When not limited the 11 `quota` field is omitted. Also says how many bytes are used by last version of 12 files and how many bytes are taken by older versions. 13 14 If the `include=trash` parameter is added to the query string, it will also 15 compute the size of the files in the trash. 16 17 #### Request 18 19 ```http 20 GET /settings/disk-usage?include=trash HTTP/1.1 21 Host: alice.example.com 22 Accept: application/vnd.api+json 23 Authorization: Bearer ... 24 ``` 25 26 #### Response 27 28 ```http 29 HTTP/1.1 200 OK 30 Content-Type: application/vnd.api+json 31 ``` 32 33 ```json 34 { 35 "data": { 36 "type": "io.cozy.settings", 37 "id": "io.cozy.settings.disk-usage", 38 "attributes": { 39 "quota": "123456789", 40 "used": "12345678", 41 "files": "10305070", 42 "trash": "456789", 43 "versions": "2040608" 44 } 45 } 46 } 47 ``` 48 49 ## OAuth clients usage 50 51 ### GET /settings/clients-usage 52 53 This endpoint returns the number of user-connected OAuth clients, the limit set 54 on the Cozy and if this limit has been reached or even exceeded. 55 If there is no limit, the `limit` attribute won't be present in the response. 56 57 #### Request 58 59 ``` 60 GET /settings/clients-usage HTTP/1.1 61 Host: alice.example.com 62 Accept: application/vnd.api+json 63 Authorization: Bearer ... 64 ``` 65 66 #### Response 67 68 ```http 69 HTTP/1.1 200 OK 70 Content-Type: application/vnd.api+json 71 ``` 72 73 ```json 74 { 75 "data": { 76 "type": "io.cozy.settings", 77 "id": "io.cozy.settings.clients-usage", 78 "attributes": { 79 "limit": 3, 80 "count": 3, 81 "limitReached": true, 82 "limitExceeded": false 83 } 84 } 85 } 86 ``` 87 88 89 ## Email update 90 91 ### POST /settings/email 92 93 The email adress update process starts with this call. The password is required 94 in order to make a strong authentication. This endpoint will send a confirmation 95 email to the new address with a link. Once clicked, this link will redirect the 96 user to the second endpoint. 97 98 #### Request 99 100 ```http 101 POST /settings/email HTTP/1.1 102 Host: alice.example.com 103 Content-Type: application/json 104 Authorization: Bearer ... 105 ``` 106 107 ```json 108 { 109 "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791", 110 "email": "alice@example.com" 111 } 112 ``` 113 114 #### Response 115 116 ```http 117 HTTP/1.1 204 No Content 118 ``` 119 120 ### POST /settings/email/resend 121 122 Once the email process is started, it's possible to resend an email in order to ensure 123 the link delivery. 124 125 #### Request 126 127 ```http 128 POST /settings/email HTTP/1.1 129 Host: alice.example.com 130 Content-Type: application/json 131 Authorization: Bearer ... 132 ``` 133 134 #### Response 135 136 ```http 137 HTTP/1.1 204 No Content 138 ``` 139 140 ### GET /settings/email/confirm 141 142 This is the second part of the email update process. The user have received a 143 confirmation email with a link on its new email adress. When he click on the link 144 he ends up on this endpoint. The url contains a token used to authenticate the user 145 and the action. 146 147 #### Request 148 149 ```http 150 GET /settings/email/confirm?token=XXXXXXX HTTP/1.1 151 Host: alice.example.com 152 ``` 153 154 #### Response 155 156 In case of success the user will be redirected to its setting page. In case of error 157 an HTML error page will appears. 158 159 ```http 160 HTTP/1.1 307 Temporary Redirect 161 Location: http://alice-settings.cozy.localhost:8080 162 ``` 163 164 165 ### DELETE /settings/email 166 167 This endpoints allows to cancel the ongoing email adress update process. 168 169 #### Request 170 171 ```http 172 DELETE /settings/email HTTP/1.1 173 Host: alice.example.com 174 Content-Type: application/json 175 Authorization: Bearer ... 176 ``` 177 178 #### Response 179 180 ```http 181 HTTP/1.1 204 No Content 182 ``` 183 184 185 ## Passphrase 186 187 The master password, known by the cozy owner, is used for two things: to allow 188 the user to login and to do encryption on the client side. To do so, two keys 189 are derivated from the master password, one for each usage. In this section, we 190 are talking about the derivated key used for login on a cozy instance. 191 192 ### GET /settings/passphrase 193 194 The server will send the parameters for hashing the master password on the 195 client side to derive a key used for login. 196 197 Note: a permission on `GET io.cozy.settings` is required for this endpoint. 198 199 #### Request 200 201 ```http 202 GET /settings/passphrase HTTP/1.1 203 Host: alice.example.com 204 Accept: application/vnd.api+json 205 Authorization: Bearer ... 206 ``` 207 208 #### Response 209 210 ```http 211 HTTP/1.1 200 OK 212 Content-Type: application/vnd.api+json 213 ``` 214 215 ```json 216 { 217 "data": { 218 "type": "io.cozy.settings", 219 "id": "io.cozy.settings.passphrase", 220 "attributes": { 221 "salt": "me@alice.example.com", 222 "kdf": 0, 223 "iterations": 10000 224 } 225 } 226 } 227 ``` 228 229 Note: only `kdf: 0` is currently supported. It means PBKDF2 with SHA256. 230 231 ### POST /settings/passphrase (form) 232 233 The user can send its new hashed passphrase (base64 encoded) to finish the 234 onboarding. The registration token can only be used once. 235 236 The `key` is the encryption key for bitwarden, encrypted with the master key. 237 The `public_key` and `private_key` are the key pair for sharing data with a 238 bitwarden organization, and they are optional. 239 240 #### Request 241 242 ```http 243 POST /settings/passphrase HTTP/1.1 244 Host: alice.example.com 245 Content-Type: application/x-www-form-urlencoded 246 247 register_token=37cddf40d7724988860fa0e03efd30fe& 248 passphrase=4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791& 249 key=0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=& 250 public_key=MIIBIjANBgkqhkiG9w...AQAB& 251 private_key=2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=& 252 iterations=100000 253 ``` 254 255 #### Response 256 257 ```http 258 HTTP/1.1 303 See Other 259 Set-Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure 260 Location: https://alice-home.example.com/ 261 ``` 262 263 ### POST /settings/passphrase (json) 264 265 The onboarding application can send a request to this endpoint to register the 266 passphrase of the user. 267 268 #### Request 269 270 ```http 271 POST /settings/passphrase HTTP/1.1 272 Host: alice.example.com 273 Content-Type: application/json 274 ``` 275 276 ```json 277 { 278 "register_token": "37cddf40d7724988860fa0e03efd30fe", 279 "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791", 280 "hint": "a hint to help me remember my passphrase", 281 "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=", 282 "public_key": "MIIBIjANBgkqhkiG9w...AQAB", 283 "private_key": "2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=", 284 "iterations": 100000 285 } 286 ``` 287 288 #### Response 289 290 ```http 291 HTTP/1.1 204 No Content 292 Set-Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure 293 ``` 294 295 ### POST /settings/passphrase/flagship 296 297 This endpoint is similar to `POST /settings/passphrase`, but it allows the 298 flagship app to also obtain OAuth access and register tokens without having to 299 make the OAuth dance (which can be awkward for the user). 300 301 #### Request 302 303 ```http 304 POST /settings/passphrase/flagship HTTP/1.1 305 Host: alice.example.com 306 Content-Type: application/json 307 ``` 308 309 ```json 310 { 311 "register_token": "37cddf40d7724988860fa0e03efd30fe", 312 "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791", 313 "hint": "a hint to help me remember my passphrase", 314 "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=", 315 "public_key": "MIIBIjANBgkqhkiG9w...AQAB", 316 "private_key": "2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=", 317 "iterations": 100000, 318 "client_id": "64ce5cb0-bd4c-11e6-880e-b3b7dfda89d3", 319 "client_secret": "eyJpc3Mi[...omitted for brevity...]" 320 } 321 ``` 322 323 #### Response 324 325 ```http 326 HTTP/1.1 200 OK 327 Content-Type: application/json 328 ``` 329 330 ```json 331 { 332 "access_token": "OWY0MjNjMGEtOTNmNi0xMWVjLWIyZGItN2I5YjgwNmRjYzBiCg", 333 "token_type": "bearer", 334 "refresh_token": "YTUwMjcyYjgtOTNmNi0xMWVjLWE4YTQtZWJhMzlmMTAwMWJiCg", 335 "scope": "*" 336 } 337 ``` 338 339 **Note:** if the OAuth client has not been certified as the flagship app, 340 this request will return: 341 342 ```http 343 HTTP/1.1 202 Accepted 344 Content-Type: application/json 345 ``` 346 347 ```json 348 { 349 "session_code": "ZmY4ODI3NGMtOTY1Yy0xMWVjLThkMDgtMmI5M2" 350 } 351 ``` 352 353 354 The `session_code` can be put in the query string while opening the OAuth 355 authorize page. It will be used to open the session, and let the user type the 356 6-digits code they have received by mail to confirm that they want to use this 357 app as the flagship app. 358 359 360 ### PUT /settings/passphrase (without two-factor authentication) 361 362 The user can change its passphrase with this route. 363 364 For users with two-factor authentication activated, a second step on the same 365 route is necessary to actually update the passphrase. See below. 366 367 A `"force": true` parameter can be added in the JSON to force a passphrase on a 368 Cozy where authentication by password is disabled and the vault is empty. It 369 allows to use Cozy Pass when the authentication on the Cozy is delegated via 370 OIDC. When forcing a password reset, you need to regenerate the 371 372 * public and private keys 373 * encryption key 374 375 of the vault and pass them via `key`, `publicKey` and `privateKey`. 376 377 See [those password-helpers](https://github.com/cozy/cozy-stack/blob/master/assets/scripts/password-helpers.js#L165-L218) for example on how to regenerate those keys. 378 379 #### Request 380 381 ```http 382 PUT /settings/passphrase HTTP/1.1 383 Host: alice.example.com 384 Content-Type: application/json 385 Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa 386 ``` 387 388 ```json 389 { 390 "current_passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791", 391 "new_passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720", 392 "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=", 393 "iterations": 10000 394 } 395 ``` 396 397 #### Response 398 399 ```http 400 HTTP/1.1 204 No Content 401 Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure 402 ``` 403 404 ### PUT /settings/passphrase (with two-factor authentication) 405 406 The user can change its passphrase with this route, with two-factor 407 authentication to verify the user with more than its passphrase. 408 409 #### Request (first step) 410 411 ```http 412 PUT /settings/passphrase HTTP/1.1 413 Host: alice.example.com 414 Content-Type: application/json 415 Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa 416 ``` 417 418 ```json 419 { 420 "current_passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791" 421 } 422 ``` 423 424 #### Response (first step) 425 426 ```http 427 HTTP/1.1 200 OK 428 Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure 429 ``` 430 431 ```json 432 { 433 "two_factor_token": "YxOSUjxd0SNmuwEEDRHXfw==" 434 } 435 ``` 436 437 At this point, the current passphrase has been exchanged against a token, and a 438 passcode should have been sent to the user to authenticate on the second step. 439 440 The token/passcode pair can be used on the second step to update the passphrase. 441 442 #### Request (second step) 443 444 ```http 445 PUT /settings/passphrase HTTP/1.1 446 Host: alice.example.com 447 Content-Type: application/json 448 Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa 449 ``` 450 451 ```json 452 { 453 "new_passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720", 454 "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=", 455 "iterations": 10000, 456 "two_factor_token": "YxOSUjxd0SNmuwEEDRHXfw==", 457 "two_factor_passcode": "4947178" 458 } 459 ``` 460 461 #### Response (second step) 462 463 ```http 464 HTTP/1.1 204 No Content 465 Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure 466 ``` 467 468 #### Response 469 470 ```http 471 HTTP/1.1 204 No Content 472 ``` 473 474 ### POST /settings/passphrase/check 475 476 This route can be used to check the passphrase of the user before making 477 important changes like asking for the Cozy deletion. 478 479 #### Request 480 481 ```http 482 POST /settings/passphrase/check HTTP/1.1 483 Host: alice.example.com 484 Content-Type: application/json 485 Authentication: Bearer xxx 486 ``` 487 488 ```json 489 { 490 "passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720" 491 } 492 ``` 493 494 #### Response 495 496 It will be `204 No Content` if the passphrase is correct, or a `403 Forbidden` if 497 the passphrase is incorrect. 498 499 ### GET /settings/hint 500 501 This route can be used to know if a hint has been chosen (but the hint won't be 502 revealed). If there is a hint, the response will be a `204 No Content`. And, if 503 not, it will be a `404 No Content`. 504 505 #### Request 506 507 ```http 508 GET /settings/hint HTTP/1.1 509 Host: alice.example.com 510 ``` 511 512 #### Response 513 514 ```http 515 HTTP/1.1 204 No Content 516 ``` 517 518 ### PUT /settings/hint 519 520 The user can change the hint for its passphrase. 521 522 #### Request 523 524 ```http 525 PUT /settings/hint HTTP/1.1 526 Host: alice.example.com 527 Content-Type: application/json 528 ``` 529 530 ```json 531 { 532 "hint": "My passphrase is very complicated" 533 } 534 ``` 535 536 #### Response 537 538 ```http 539 HTTP/1.1 204 No Content 540 ``` 541 542 ### POST /settings/vault 543 544 This route can be used to ensure the vault is initialized. If it is not the 545 case, it will migrate the accounts from the konnectors accounts to the vault 546 and will set the `extension_installed` flag. 547 548 #### Request 549 550 ```http 551 POST /settings/vault HTTP/1.1 552 Host: alice.example.com 553 ``` 554 555 #### Response 556 557 ```http 558 HTTP/1.1 204 No Content 559 ``` 560 561 ## Instance 562 563 ### GET /settings/capabilities 564 565 List the activated capabilities for this instance. An unadvertised capability 566 should be considered `false` and, for backward compatibility, if you can't get a 567 valid response from this endpoint (in particular in case of a `404 Not found` 568 error), all capabilities should be considered `false`. The current capabilities 569 are: 570 571 - `file_versioning` is true when the VFS can create 572 [old versions](https://docs.cozy.io/en/cozy-stack/files/#versions) of a file 573 - `flat_subdomains` is true when the stack is configured to use flat subdomains 574 (not nested) 575 - `can_auth_with_password` is true when authentication with a Cozy password is 576 possible 577 - `can_auth_with_magic_links` is true when authentication with a link sent by 578 email is possible 579 - `can_auth_with_oidc` is true when delegated authentication with OIDC is 580 possible for this instance. 581 582 **Note:** both `can_auth_with_password` and `can_auth_with_oidc` can be true 583 for an instance where the choice is given to the user of how they want to 584 authenticate. 585 586 #### Request 587 588 ```http 589 GET /settings/capabilities HTTP/1.1 590 Host: alice.example.com 591 Accept: application/vnd.api+json 592 ``` 593 594 #### Response 595 596 ```json 597 { 598 "data": { 599 "type": "io.cozy.settings", 600 "id": "io.cozy.settings.capabilities", 601 "attributes": { 602 "file_versioning": true, 603 "flat_subdomains": false, 604 "can_auth_with_password": true, 605 "can_auth_with_magic_links": false, 606 "can_auth_with_oidc": false 607 }, 608 "links": { 609 "self": "/settings/capabilities" 610 } 611 } 612 } 613 ``` 614 615 #### Permissions 616 617 No permissions are required to access this route, but the request needs to be 618 authenticated (webapp token, OAuth token, etc.). 619 620 ### GET /settings/external-ties 621 622 List ties between the instance and external services such as a subscription 623 vendor (e.g. mobile app stores). 624 The current possible ties are: 625 626 - `has_blocking_subscription` is true when the instance is linked to a premium 627 subscription paid via a third-party vendor that does not let us cancel the 628 subscription ourselves and requires it to be cancelled by the customer 629 themselves. 630 631 #### Request 632 633 ```http 634 GET /settings/external-ties HTTP/1.1 635 Host: alice.example.com 636 Accept: application/vnd.api+json 637 ``` 638 639 #### Response 640 641 ```json 642 { 643 "data": { 644 "type": "io.cozy.settings", 645 "id": "io.cozy.settings.external-ties", 646 "attributes": { 647 "has_blocking_subscription": false 648 }, 649 "links": { 650 "self": "/settings/external-ties" 651 } 652 } 653 } 654 ``` 655 656 #### Permissions 657 658 No permissions are required to access this route, but the request needs to be 659 made from an authenticated Web session or Webapp. 660 661 ### GET /settings/instance 662 663 If the user is logged in, display all instance settings. 664 665 #### Request 666 667 ```http 668 GET /settings/instance HTTP/1.1 669 Host: alice.example.com 670 Accept: application/vnd.api+json 671 Cookie: sessionid=xxxx 672 ``` 673 674 #### Response 675 676 ```json 677 { 678 "data": { 679 "type": "io.cozy.settings", 680 "id": "io.cozy.settings.instance", 681 "meta": { 682 "rev": "3-56521545485448482" 683 }, 684 "attributes": { 685 "locale": "fr", 686 "password_defined": true, 687 "auto_update": true, 688 "email": "alice@example.com", 689 "public_name": "Alice Martin", 690 "auth_mode": "basic", 691 "default_redirection": "drive/#/folder", 692 "context": "dev", 693 "sponsorships": ["springfield"] 694 } 695 } 696 } 697 ``` 698 699 #### Note about `password_defined` 700 701 There are a few fields that are persisted on the instance its-self, not on its 702 settings document. When they are updated, it won't be reflected in the realtime 703 when listening on the `io.cozy.settings.instance` document. 704 705 For `password_defined`, it is possible to be notified when the password is 706 defined by watching a synthetic document with the doctype `io.cozy.settings`, 707 and the id `io.cozy.settings.passphrase`. 708 709 ### POST /settings/instance/deletion 710 711 The settings application can use this route if the user wants to delete their 712 Cozy instance. 713 714 #### Request 715 716 ```http 717 POST /settings/instance/deletion HTTP/1.1 718 Host: alice.example.com 719 ``` 720 721 #### Response 722 723 ```http 724 HTTP/1.1 204 No Content 725 ``` 726 727 ### DELETE /settings/instance/moved_from 728 729 When there is an attribute `moved_from` in the instance settings, it means that 730 the Cozy has been moved from the given address. The Home application uses this 731 information to display a modal to alert the user. And when they dismiss the modal, 732 a request is made to this route to remove this information (and avoid showing 733 this modal again the next time they will open the Home again). 734 735 #### Request 736 737 ```http 738 DELETE /settings/instance/moved_from HTTP/1.1 739 Host: target.cozy.localhost 740 Cookie: sessionid=xxxxx 741 ``` 742 743 #### Response 744 745 ```http 746 HTTP/1.1 204 No Content 747 ``` 748 749 #### Permissions 750 751 No permission is required to use this route, only that the user is logged-in. 752 753 ### PUT /settings/instance 754 755 If the user is logged in, allow to set the instance fields 756 757 #### Request 758 759 ```http 760 POST /settings/instance HTTP/1.1 761 Host: alice.example.com 762 Accept: application/vnd.api+json 763 Content-Type: application/vnd.api+json 764 Cookie: sessionid=xxxxx 765 Authorization: Bearer settings-token 766 ``` 767 768 ```json 769 { 770 "data": { 771 "type": "io.cozy.settings", 772 "id": "io.cozy.settings.instance", 773 "meta": { 774 "rev": "3-56521545485448482" 775 }, 776 "attributes": { 777 "locale": "fr", 778 "email": "alice@example.com", 779 "public_name": "Alice Martin", 780 "timezone": "Europe/Berlin", 781 "auth_mode": "two_factor_mail", 782 "default_redirection": "drive/#/folder" 783 } 784 } 785 } 786 ``` 787 788 Note: the format for `default_redirection` is the application slug, followed by 789 a slash, and then the route for the app (path + fragment). 790 791 #### Response 792 793 ``` 794 HTTP/1.1 200 OK 795 Content-Type: application/json 796 ``` 797 798 ```json 799 { 800 "data": { 801 "type": "io.cozy.settings", 802 "id": "io.cozy.settings.instance", 803 "meta": { 804 "rev": "4-5a3e315e" 805 }, 806 "attributes": { 807 "locale": "fr", 808 "email": "alice@example.com", 809 "public_name": "Alice Martin", 810 "timezone": "Europe/Berlin", 811 "auth_mode": "two_factor_mail", 812 "default_redirection": "drive/#/folder" 813 } 814 } 815 } 816 ``` 817 818 #### Permissions 819 820 To use this endpoint, an application needs a permission on the type 821 `io.cozy.settings` for the verb `PUT`. 822 823 ### PUT /settings/instance/auth_mode 824 825 With this route, the user can ask for the activation of different authentication 826 modes, like two-factor authentication. 827 828 Available authentication modes: 829 830 - `basic`: basic authentication only with passphrase 831 - `two_factor_mail`: authentication with passphrase and validation with a code 832 sent via email to the user. 833 834 When asking for activation of the two-factor authentication, a side-effect can 835 be triggered to send the user its code (via email for instance), and the 836 activation not being effective. This side-effect should provide the user with a 837 code that can be used to finalize the activation of the two-factor 838 authentication. 839 840 Hence, this route has two behaviors: 841 842 - the code is not provided: the route is a side effect to ask for the 843 activation of 2FA, and a code is sent 844 - the code is provided, and valid: the two-factor authentication is actually 845 activated. 846 847 Status codes: 848 849 - `204 No Content`: when the mail has been confirmed and two-factor 850 authentication is activated 851 - `422 Unprocessable Entity`: when the given confirmation code is not good. 852 853 #### Request 854 855 ```http 856 PUT /settings/instance/auth_mode HTTP/1.1 857 Host: alice.example.com 858 Content-Type: application/json 859 Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa 860 ``` 861 862 ```json 863 { 864 "auth_mode": "two_factor_mail", 865 "two_factor_activation_code": "12345678" 866 } 867 ``` 868 869 ### PUT /settings/instance/sign_tos 870 871 With this route, an OAuth client can sign the new TOS version. 872 873 Status codes: 874 875 - `204 No Content`: when the mail has been confirmed and two-factor 876 authentication is activated 877 878 #### Request 879 880 ```http 881 PUT /settings/instance/sign_tos HTTP/1.1 882 Host: alice.example.com 883 Content-Type: application/json 884 Authorization: Bearer ... 885 ``` 886 887 ## Sessions 888 889 ### GET /settings/sessions 890 891 This route allows to get all the currently active sessions. 892 893 ``` 894 GET /settings/sessions HTTP/1.1 895 Host: cozy.example.org 896 Cookie: ... 897 Authorization: Bearer ... 898 ``` 899 900 ```http 901 HTTP/1.1 200 OK 902 Content-Type: application/json 903 ``` 904 905 ```json 906 { 907 "data": [ 908 { 909 "id": "...", 910 "attributes": { 911 "last_seen": "" 912 }, 913 "meta": { 914 "rev": "..." 915 } 916 } 917 ] 918 } 919 ``` 920 921 #### Permissions 922 923 This route requires the application to have permissions on the 924 `io.cozy.sessions` doctype with the `GET` verb. 925 926 ## OAuth 2 clients 927 928 ### GET /settings/clients 929 930 Get the list of the registered clients 931 932 #### Request 933 934 ```http 935 GET /settings/clients HTTP/1.1 936 Host: alice.example.com 937 Accept: application/vnd.api+json 938 Cookie: sessionid=xxxxx 939 Authorization: Bearer oauth2-clients-token 940 ``` 941 942 #### Response 943 944 ```http 945 HTTP/1.1 200 OK 946 Content-Type: application/vnd.api+json 947 ``` 948 949 ```json 950 { 951 "data": [ 952 { 953 "type": "io.cozy.oauth.clients", 954 "id": "30e84c10-e6cf-11e6-9bfd-a7106972de51", 955 "attributes": { 956 "redirect_uris": ["http://localhost:4000/oauth/callback"], 957 "client_name": "Cozy-Desktop on my-new-laptop", 958 "client_kind": "desktop", 959 "client_uri": "https://docs.cozy.io/en/mobile/desktop.html", 960 "logo_uri": "https://docs.cozy.io/assets/images/cozy-logo-docs.svg", 961 "policy_uri": "https://cozy.io/policy", 962 "software_id": "/github.com/cozy-labs/cozy-desktop", 963 "software_version": "0.16.0", 964 "client_os": "Windows", 965 "last_refreshed_at": "2017-09-04T08:14:47Z", 966 "synchronized_at": "2017-09-05T16:23:04Z" 967 }, 968 "links": { 969 "self": "/settings/clients/30e84c10-e6cf-11e6-9bfd-a7106972de51" 970 } 971 } 972 ] 973 } 974 ``` 975 976 #### Permissions 977 978 To use this endpoint, an application needs a permission on the type 979 `io.cozy.oauth.clients` for the verb `GET` (only client-side apps). 980 981 ### DELETE /settings/clients/:client-id 982 983 #### Request 984 985 ```http 986 DELETE /settings/clients/30e84c10-e6cf-11e6-9bfd-a7106972de51 HTTP/1.1 987 Host: alice.example.com 988 Authorization: Bearer oauth2-clients-token 989 ``` 990 991 #### Response 992 993 ```http 994 HTTP/1.1 204 No Content 995 ``` 996 997 #### Permissions 998 999 To use this endpoint, an application needs a permission on the type 1000 `io.cozy.oauth.clients` for the verb `DELETE` (only client-side apps). 1001 1002 ### GET /settings/clients/limit-exceeded 1003 1004 Get an OAuth clients limit exceeded page if the instance has more connected 1005 OAuth clients than its limit allows or redirect the request to the `redirect` 1006 parameter's value. 1007 The `redirect` parameter is optional. By default, its value 1008 is the instance's default redirection. 1009 1010 The page will auto-refresh every 20 seconds or when an OAuth client deletion is 1011 detected. 1012 1013 #### Query-String 1014 1015 | Parameter | Description | 1016 | ---------- | ---------------------------------------------------- | 1017 | redirect | URL where to redirect when the limit is not exceeded | 1018 1019 #### Request 1020 1021 ```http 1022 GET /settings/clients/limit-exceeded?redirect=https%3A%2F%2Falice-home.example.com%2F HTTP/1.1 1023 Host: alice.example.com 1024 Accept: application/vnd.api+json 1025 Cookie: sessionid=xxxx 1026 ``` 1027 1028 ### POST /settings/synchronized 1029 1030 Any OAuth2 client can make a request to this endpoint with its token, no 1031 permission is needed. It will update the date of last synchronization for this 1032 device. 1033 1034 #### Request 1035 1036 ```http 1037 POST /settings/synchronized HTTP/1.1 1038 Host: alice.example.com 1039 Authorization: Bearer oauth2-access-token 1040 ``` 1041 1042 #### Response 1043 1044 ```http 1045 HTTP/1.1 204 No Content 1046 ``` 1047 1048 ## Context 1049 1050 ### GET /settings/onboarded 1051 1052 It redirects the user to an application after the onboarding. The application is 1053 selected according to the context of the instance and the configuration of the 1054 stack. 1055 1056 ### GET /settings/install_flagship_app 1057 1058 At the end of an onboarding, just after the password has been chosen, if the 1059 user is in a mobile browser, the stack will show a page to push them to install 1060 the flagship app. 1061 1062 ### GET /settings/context 1063 1064 It gives the keys/values from the config for the context of the instance. 1065 1066 #### Request 1067 1068 ```http 1069 GET /settings/context HTTP/1.1 1070 Host: alice.example.com 1071 Accept: application/vnd.api+json 1072 Cookie: sessionid=xxxx 1073 ``` 1074 1075 #### Response 1076 1077 ```json 1078 { 1079 "data": { 1080 "type": "io.cozy.settings", 1081 "id": "io.cozy.settings.context", 1082 "attributes": { 1083 "default_redirection": "drive/#/folder", 1084 "help_link": "https://forum.cozy.io/", 1085 "onboarded_redirection": "home/#/discovery/?intro" 1086 }, 1087 "links": { 1088 "self": "/settings/context" 1089 } 1090 } 1091 } 1092 ``` 1093 1094 #### Permissions 1095 1096 To use this endpoint, an application needs a valid token, but no explicit 1097 permission is required. 1098 1099 ## Feature flags 1100 1101 A feature flag is a name and an associated value (boolean, number, string or a 1102 JSON) that can be interpreted by the apps. It can be used for giving access to 1103 paid features, or to enable a feature progressively on all the cozy instances 1104 of a context. The stack computes the feature flags from several sources (in 1105 order of decreasing priority): 1106 1107 - the flags set on the instance by the command `cozy-stack feature flags` 1108 - the response of the manager for `GET /api/v1/flags?sets=s1,s2&context=ctx` 1109 (where `s1,s2` has been set via `cozy-stack feature sets`) 1110 - the flags coming from the context configuration (`context.<name>.features`) 1111 - the flags set on the context by the command `cozy-stack feature ratio` 1112 - the default value (`cozy-stack feature default`). 1113 1114 For a given flag, the stack takes the value from the source with the highest 1115 priority, and does not look at the other sources (no merge). 1116 1117 ### GET /settings/flags 1118 1119 This endpoint returns the computed list of feature flags for the given 1120 instance. It accepts an `include` parameter in the query string to see the 1121 details of how the flags were computed. 1122 1123 #### Request 1124 1125 ```http 1126 GET /settings/flags HTTP/1.1 1127 Host: alice.example.com 1128 Accept: application/vnd.api+json 1129 ``` 1130 1131 #### Response 1132 1133 ```http 1134 HTTP/1.1 200 OK 1135 Content-Type: application/vnd.api+json 1136 ``` 1137 1138 ```json 1139 { 1140 "data": { 1141 "type": "io.cozy.settings", 1142 "id": "io.cozy.settings.flags", 1143 "attributes": { 1144 "has_feature1": true, 1145 "has_feature2": false, 1146 "number_of_foos": 10, 1147 "bar_config": { "qux": "quux" } 1148 }, 1149 "links": { 1150 "self": "/settings/flags" 1151 } 1152 } 1153 } 1154 ``` 1155 1156 #### Request 1157 1158 ```http 1159 GET /settings/flags?include=source HTTP/1.1 1160 Host: alice.example.com 1161 Accept: application/vnd.api+json 1162 ``` 1163 1164 #### Response 1165 1166 ```http 1167 HTTP/1.1 200 OK 1168 Content-Type: application/vnd.api+json 1169 ``` 1170 1171 ```json 1172 { 1173 "data": { 1174 "type": "io.cozy.settings", 1175 "id": "io.cozy.settings.flags", 1176 "attributes": { 1177 "has_feature1": true, 1178 "has_feature2": false, 1179 "number_of_foos": 10, 1180 "bar_config": { "qux": "quux" } 1181 }, 1182 "links": { 1183 "self": "/settings/flags" 1184 } 1185 }, 1186 "included": [ 1187 { 1188 "type": "io.cozy.settings", 1189 "id": "io.cozy.settings.flags.instance", 1190 "attributes": { 1191 "number_of_foos": 10 1192 } 1193 }, 1194 { 1195 "type": "io.cozy.settings", 1196 "id": "io.cozy.settings.flags.manager", 1197 "attributes": { 1198 "sets": ["s1", "s2"], 1199 "has_feature1": true, 1200 "number_of_foos": 5 1201 } 1202 }, 1203 { 1204 "type": "io.cozy.settings", 1205 "id": "io.cozy.settings.flags.config", 1206 "attributes": { 1207 "number_of_foos": 2 1208 } 1209 }, 1210 { 1211 "type": "io.cozy.settings", 1212 "id": "io.cozy.settings.flags.context", 1213 "attributes": { 1214 "has_feature2": [{ "ratio": 0.1, "value": true }], 1215 "bar_config": [ 1216 { "ratio": 0.2, "value": { "qux": "quux" } }, 1217 { "ratio": 0.8, "value": { "qux": "baz" } } 1218 ] 1219 } 1220 }, 1221 { 1222 "type": "io.cozy.settings", 1223 "id": "io.cozy.settings.flags.default", 1224 "attributes": { 1225 "bar_config": { "qux": "courge" }, 1226 "number_of_foos": 2 1227 } 1228 } 1229 ] 1230 } 1231 ``` 1232 1233 #### Permissions 1234 1235 To use this endpoint, an application needs a valid token, but no explicit 1236 permission is required.