Skip to content

Table of contents

Settings

Disk usage

GET /settings/disk-usage

Says how many bytes are available and used to store files. When not limited the quota field is omitted. Also says how many bytes are used by last version of files and how many bytes are taken by older versions.

If the include=trash parameter is added to the query string, it will also compute the size of the files in the trash.

Request

GET /settings/disk-usage?include=trash HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Authorization: Bearer ...

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.disk-usage",
        "attributes": {
            "quota": "123456789",
            "used": "12345678",
            "files": "10305070",
            "trash": "456789",
            "versions": "2040608"
        }
    }
}

OAuth clients usage

GET /settings/clients-usage

This endpoint returns the number of user-connected OAuth clients, the limit set on the Cozy and if this limit has been reached or even exceeded. If there is no limit, the limit attribute won’t be present in the response.

Request

GET /settings/clients-usage HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Authorization: Bearer ...

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.clients-usage",
        "attributes": {
          "limit": 3,
          "count": 3,
          "limitReached": true,
          "limitExceeded": false
        }
    }
}

Email update

POST /settings/email

The email adress update process starts with this call. The password is required in order to make a strong authentication. This endpoint will send a confirmation email to the new address with a link. Once clicked, this link will redirect the user to the second endpoint.

Request

POST /settings/email HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Authorization: Bearer ...
{
    "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791",
    "email": "alice@example.com"
}

Response

HTTP/1.1 204 No Content

POST /settings/email/resend

Once the email process is started, it’s possible to resend an email in order to ensure the link delivery.

Request

POST /settings/email HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Authorization: Bearer ...

Response

HTTP/1.1 204 No Content

GET /settings/email/confirm

This is the second part of the email update process. The user have received a confirmation email with a link on its new email adress. When he click on the link he ends up on this endpoint. The url contains a token used to authenticate the user and the action.

Request

GET /settings/email/confirm?token=XXXXXXX HTTP/1.1
Host: alice.example.com

Response

In case of success the user will be redirected to its setting page. In case of error an HTML error page will appears.

HTTP/1.1 307 Temporary Redirect
Location: http://alice-settings.cozy.localhost:8080 

DELETE /settings/email

This endpoints allows to cancel the ongoing email adress update process.

Request

DELETE /settings/email HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Authorization: Bearer ...

Response

HTTP/1.1 204 No Content

Passphrase

The master password, known by the cozy owner, is used for two things: to allow the user to login and to do encryption on the client side. To do so, two keys are derivated from the master password, one for each usage. In this section, we are talking about the derivated key used for login on a cozy instance.

GET /settings/passphrase

The server will send the parameters for hashing the master password on the client side to derive a key used for login.

Note: a permission on GET io.cozy.settings is required for this endpoint.

Request

GET /settings/passphrase HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Authorization: Bearer ...

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.passphrase",
        "attributes": {
            "salt": "me@alice.example.com",
            "kdf": 0,
            "iterations": 10000
        }
    }
}

Note: only kdf: 0 is currently supported. It means PBKDF2 with SHA256.

POST /settings/passphrase (form)

The user can send its new hashed passphrase (base64 encoded) to finish the onboarding. The registration token can only be used once.

The key is the encryption key for bitwarden, encrypted with the master key. The public_key and private_key are the key pair for sharing data with a bitwarden organization, and they are optional.

Request

POST /settings/passphrase HTTP/1.1
Host: alice.example.com
Content-Type: application/x-www-form-urlencoded

register_token=37cddf40d7724988860fa0e03efd30fe&
passphrase=4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791&
key=0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=&
public_key=MIIBIjANBgkqhkiG9w...AQAB&
private_key=2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=&
iterations=100000

Response

HTTP/1.1 303 See Other
Set-Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure
Location: https://alice-home.example.com/

POST /settings/passphrase (json)

The onboarding application can send a request to this endpoint to register the passphrase of the user.

Request

POST /settings/passphrase HTTP/1.1
Host: alice.example.com
Content-Type: application/json
{
    "register_token": "37cddf40d7724988860fa0e03efd30fe",
    "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791",
    "hint": "a hint to help me remember my passphrase",
    "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=",
    "public_key": "MIIBIjANBgkqhkiG9w...AQAB",
    "private_key": "2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=",
    "iterations": 100000
}

Response

HTTP/1.1 204 No Content
Set-Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure

POST /settings/passphrase/flagship

This endpoint is similar to POST /settings/passphrase, but it allows the flagship app to also obtain OAuth access and register tokens without having to make the OAuth dance (which can be awkward for the user).

Request

POST /settings/passphrase/flagship HTTP/1.1
Host: alice.example.com
Content-Type: application/json
{
    "register_token": "37cddf40d7724988860fa0e03efd30fe",
    "passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791",
    "hint": "a hint to help me remember my passphrase",
    "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=",
    "public_key": "MIIBIjANBgkqhkiG9w...AQAB",
    "private_key": "2.wZuKkufLV31Cpw1v1TQUDA==|u6bUNTaaGxu...y7s=",
    "iterations": 100000,
    "client_id": "64ce5cb0-bd4c-11e6-880e-b3b7dfda89d3",
    "client_secret": "eyJpc3Mi[...omitted for brevity...]"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "OWY0MjNjMGEtOTNmNi0xMWVjLWIyZGItN2I5YjgwNmRjYzBiCg",
  "token_type": "bearer",
  "refresh_token": "YTUwMjcyYjgtOTNmNi0xMWVjLWE4YTQtZWJhMzlmMTAwMWJiCg",
  "scope": "*"
}

Note: if the OAuth client has not been certified as the flagship app, this request will return:

HTTP/1.1 202 Accepted
Content-Type: application/json
{
  "session_code": "ZmY4ODI3NGMtOTY1Yy0xMWVjLThkMDgtMmI5M2"
}

The session_code can be put in the query string while opening the OAuth authorize page. It will be used to open the session, and let the user type the 6-digits code they have received by mail to confirm that they want to use this app as the flagship app.

PUT /settings/passphrase (without two-factor authentication)

The user can change its passphrase with this route.

For users with two-factor authentication activated, a second step on the same route is necessary to actually update the passphrase. See below.

A "force": true parameter can be added in the JSON to force a passphrase on a Cozy where authentication by password is disabled and the vault is empty. It allows to use Cozy Pass when the authentication on the Cozy is delegated via OIDC. When forcing a password reset, you need to regenerate the

  • public and private keys
  • encryption key

of the vault and pass them via key, publicKey and privateKey.

See those password-helpers for example on how to regenerate those keys.

Request

PUT /settings/passphrase HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa
{
    "current_passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791",
    "new_passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720",
    "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=",
    "iterations": 10000
}

Response

HTTP/1.1 204 No Content
Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure

PUT /settings/passphrase (with two-factor authentication)

The user can change its passphrase with this route, with two-factor authentication to verify the user with more than its passphrase.

Request (first step)

PUT /settings/passphrase HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa
{
    "current_passphrase": "4f58133ea0f415424d0a856e0d3d2e0cd28e4358fce7e333cb524729796b2791"
}

Response (first step)

HTTP/1.1 200 OK
Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure
{
    "two_factor_token": "YxOSUjxd0SNmuwEEDRHXfw=="
}

At this point, the current passphrase has been exchanged against a token, and a passcode should have been sent to the user to authenticate on the second step.

The token/passcode pair can be used on the second step to update the passphrase.

Request (second step)

PUT /settings/passphrase HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa
{
    "new_passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720",
    "key": "0.uRcMe+Mc2nmOet4yWx9BwA==|PGQhpYUlTUq/vBEDj1KOHVMlTIH1eecMl0j80+Zu0VRVfFa7X/MWKdVM6OM/NfSZicFEwaLWqpyBlOrBXhR+trkX/dPRnfwJD2B93hnLNGQ=",
    "iterations": 10000,
    "two_factor_token": "YxOSUjxd0SNmuwEEDRHXfw==",
    "two_factor_passcode": "4947178"
}

Response (second step)

HTTP/1.1 204 No Content
Set-Cookie: cozysessid=AAAAShoo3uo1Maic4VibuGohlik2eKUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa; Path=/; Domain=alice.example.com; Max-Age=604800; HttpOnly; Secure

Response

HTTP/1.1 204 No Content

POST /settings/passphrase/check

This route can be used to check the passphrase of the user before making important changes like asking for the Cozy deletion.

Request

POST /settings/passphrase/check HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Authentication: Bearer xxx
{
    "passphrase": "2e7e1e04300356adc8fabf5d304b58c564399746cc7a21464fd6593edd925720"
}

Response

It will be 204 No Content if the passphrase is correct, or a 403 Forbidden if the passphrase is incorrect.

GET /settings/hint

This route can be used to know if a hint has been chosen (but the hint won’t be revealed). If there is a hint, the response will be a 204 No Content. And, if not, it will be a 404 No Content.

Request

GET /settings/hint HTTP/1.1
Host: alice.example.com

Response

HTTP/1.1 204 No Content

PUT /settings/hint

The user can change the hint for its passphrase.

Request

PUT /settings/hint HTTP/1.1
Host: alice.example.com
Content-Type: application/json
{
  "hint": "My passphrase is very complicated"
}

Response

HTTP/1.1 204 No Content

POST /settings/vault

This route can be used to ensure the vault is initialized. If it is not the case, it will migrate the accounts from the konnectors accounts to the vault and will set the extension_installed flag.

Request

POST /settings/vault HTTP/1.1
Host: alice.example.com

Response

HTTP/1.1 204 No Content

Instance

GET /settings/capabilities

List the activated capabilities for this instance. An unadvertised capability should be considered false and, for backward compatibility, if you can’t get a valid response from this endpoint (in particular in case of a 404 Not found error), all capabilities should be considered false. The current capabilities are:

  • file_versioning is true when the VFS can create old versions of a file
  • flat_subdomains is true when the stack is configured to use flat subdomains (not nested)
  • can_auth_with_password is true when authentication with a Cozy password is possible
  • can_auth_with_magic_links is true when authentication with a link sent by email is possible
  • can_auth_with_oidc is true when delegated authentication with OIDC is possible for this instance.

Note: both can_auth_with_password and can_auth_with_oidc can be true for an instance where the choice is given to the user of how they want to authenticate.

Request

GET /settings/capabilities HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json

Response

{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.capabilities",
        "attributes": {
            "file_versioning": true,
            "flat_subdomains": false,
            "can_auth_with_password": true,
            "can_auth_with_magic_links": false,
            "can_auth_with_oidc": false
        },
        "links": {
            "self": "/settings/capabilities"
        }
    }
}

Permissions

No permissions are required to access this route, but the request needs to be authenticated (webapp token, OAuth token, etc.).

GET /settings/external-ties

List ties between the instance and external services such as a subscription vendor (e.g. mobile app stores). The current possible ties are:

  • has_blocking_subscription is true when the instance is linked to a premium subscription paid via a third-party vendor that does not let us cancel the subscription ourselves and requires it to be cancelled by the customer themselves.

Request

GET /settings/external-ties HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json

Response

{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.external-ties",
        "attributes": {
            "has_blocking_subscription": false
        },
        "links": {
            "self": "/settings/external-ties"
        }
    }
}

Permissions

No permissions are required to access this route, but the request needs to be made from an authenticated Web session or Webapp.

GET /settings/instance

If the user is logged in, display all instance settings.

Request

GET /settings/instance HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Cookie: sessionid=xxxx

Response

{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.instance",
        "meta": {
            "rev": "3-56521545485448482"
        },
        "attributes": {
            "locale": "fr",
            "password_defined": true,
            "auto_update": true,
            "email": "alice@example.com",
            "public_name": "Alice Martin",
            "auth_mode": "basic",
            "default_redirection": "drive/#/folder",
            "context": "dev",
            "sponsorships": ["springfield"]
        }
    }
}

Note about password_defined

There are a few fields that are persisted on the instance its-self, not on its settings document. When they are updated, it won’t be reflected in the realtime when listening on the io.cozy.settings.instance document.

For password_defined, it is possible to be notified when the password is defined by watching a synthetic document with the doctype io.cozy.settings, and the id io.cozy.settings.passphrase.

POST /settings/instance/deletion

The settings application can use this route if the user wants to delete their Cozy instance.

Request

POST /settings/instance/deletion HTTP/1.1
Host: alice.example.com

Response

HTTP/1.1 204 No Content

DELETE /settings/instance/moved_from

When there is an attribute moved_from in the instance settings, it means that the Cozy has been moved from the given address. The Home application uses this information to display a modal to alert the user. And when they dismiss the modal, a request is made to this route to remove this information (and avoid showing this modal again the next time they will open the Home again).

Request

DELETE /settings/instance/moved_from HTTP/1.1
Host: target.cozy.localhost
Cookie: sessionid=xxxxx

Response

HTTP/1.1 204 No Content

Permissions

No permission is required to use this route, only that the user is logged-in.

PUT /settings/instance

If the user is logged in, allow to set the instance fields

Request

POST /settings/instance HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Cookie: sessionid=xxxxx
Authorization: Bearer settings-token
{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.instance",
        "meta": {
            "rev": "3-56521545485448482"
        },
        "attributes": {
            "locale": "fr",
            "email": "alice@example.com",
            "public_name": "Alice Martin",
            "timezone": "Europe/Berlin",
            "auth_mode": "two_factor_mail",
            "default_redirection": "drive/#/folder"
        }
    }
}

Note: the format for default_redirection is the application slug, followed by a slash, and then the route for the app (path + fragment).

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.instance",
        "meta": {
            "rev": "4-5a3e315e"
        },
        "attributes": {
            "locale": "fr",
            "email": "alice@example.com",
            "public_name": "Alice Martin",
            "timezone": "Europe/Berlin",
            "auth_mode": "two_factor_mail",
            "default_redirection": "drive/#/folder"
        }
    }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.settings for the verb PUT.

PUT /settings/instance/auth_mode

With this route, the user can ask for the activation of different authentication modes, like two-factor authentication.

Available authentication modes:

  • basic: basic authentication only with passphrase
  • two_factor_mail: authentication with passphrase and validation with a code sent via email to the user.

When asking for activation of the two-factor authentication, a side-effect can be triggered to send the user its code (via email for instance), and the activation not being effective. This side-effect should provide the user with a code that can be used to finalize the activation of the two-factor authentication.

Hence, this route has two behaviors:

  • the code is not provided: the route is a side effect to ask for the activation of 2FA, and a code is sent
  • the code is provided, and valid: the two-factor authentication is actually activated.

Status codes:

  • 204 No Content: when the mail has been confirmed and two-factor authentication is activated
  • 422 Unprocessable Entity: when the given confirmation code is not good.

Request

PUT /settings/instance/auth_mode HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Cookie: cozysessid=AAAAAFhSXT81MWU0ZTBiMzllMmI1OGUyMmZiN2Q0YTYzNDAxN2Y5NjCmp2Ja56hPgHwufpJCBBGJC2mLeJ5LCRrFFkHwaVVa
{
    "auth_mode": "two_factor_mail",
    "two_factor_activation_code": "12345678"
}

PUT /settings/instance/sign_tos

With this route, an OAuth client can sign the new TOS version.

Status codes:

  • 204 No Content: when the mail has been confirmed and two-factor authentication is activated

Request

PUT /settings/instance/sign_tos HTTP/1.1
Host: alice.example.com
Content-Type: application/json
Authorization: Bearer ...

Sessions

GET /settings/sessions

This route allows to get all the currently active sessions.

GET /settings/sessions HTTP/1.1
Host: cozy.example.org
Cookie: ...
Authorization: Bearer ...
HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": [
        {
            "id": "...",
            "attributes": {
                "last_seen": ""
            },
            "meta": {
                "rev": "..."
            }
        }
    ]
}

Permissions

This route requires the application to have permissions on the io.cozy.sessions doctype with the GET verb.

OAuth 2 clients

GET /settings/clients

Get the list of the registered clients

Request

GET /settings/clients HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Cookie: sessionid=xxxxx
Authorization: Bearer oauth2-clients-token

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
    "data": [
        {
            "type": "io.cozy.oauth.clients",
            "id": "30e84c10-e6cf-11e6-9bfd-a7106972de51",
            "attributes": {
                "redirect_uris": ["http://localhost:4000/oauth/callback"],
                "client_name": "Cozy-Desktop on my-new-laptop",
                "client_kind": "desktop",
                "client_uri": "https://docs.cozy.io/en/mobile/desktop.html",
                "logo_uri": "https://docs.cozy.io/assets/images/cozy-logo-docs.svg",
                "policy_uri": "https://cozy.io/policy",
                "software_id": "/github.com/cozy-labs/cozy-desktop",
                "software_version": "0.16.0",
                "client_os": "Windows",
                "last_refreshed_at": "2017-09-04T08:14:47Z",
                "synchronized_at": "2017-09-05T16:23:04Z"
            },
            "links": {
                "self": "/settings/clients/30e84c10-e6cf-11e6-9bfd-a7106972de51"
            }
        }
    ]
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.oauth.clients for the verb GET (only client-side apps).

DELETE /settings/clients/:client-id

Request

DELETE /settings/clients/30e84c10-e6cf-11e6-9bfd-a7106972de51 HTTP/1.1
Host: alice.example.com
Authorization: Bearer oauth2-clients-token

Response

HTTP/1.1 204 No Content

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.oauth.clients for the verb DELETE (only client-side apps).

GET /settings/clients/limit-exceeded

Get an OAuth clients limit exceeded page if the instance has more connected OAuth clients than its limit allows or redirect the request to the redirect parameter’s value. The redirect parameter is optional. By default, its value is the instance’s default redirection.

The page will auto-refresh every 20 seconds or when an OAuth client deletion is detected.

Query-String

Parameter Description
redirect URL where to redirect when the limit is not exceeded

Request

GET /settings/clients/limit-exceeded?redirect=https%3A%2F%2Falice-home.example.com%2F HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Cookie: sessionid=xxxx

POST /settings/synchronized

Any OAuth2 client can make a request to this endpoint with its token, no permission is needed. It will update the date of last synchronization for this device.

Request

POST /settings/synchronized HTTP/1.1
Host: alice.example.com
Authorization: Bearer oauth2-access-token

Response

HTTP/1.1 204 No Content

Context

GET /settings/onboarded

It redirects the user to an application after the onboarding. The application is selected according to the context of the instance and the configuration of the stack.

GET /settings/install_flagship_app

At the end of an onboarding, just after the password has been chosen, if the user is in a mobile browser, the stack will show a page to push them to install the flagship app.

GET /settings/context

It gives the keys/values from the config for the context of the instance.

Request

GET /settings/context HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json
Cookie: sessionid=xxxx

Response

{
    "data": {
        "type": "io.cozy.settings",
        "id": "io.cozy.settings.context",
        "attributes": {
            "default_redirection": "drive/#/folder",
            "help_link": "https://forum.cozy.io/",
            "onboarded_redirection": "home/#/discovery/?intro"
        },
        "links": {
            "self": "/settings/context"
        }
    }
}

Permissions

To use this endpoint, an application needs a valid token, but no explicit permission is required.

Feature flags

A feature flag is a name and an associated value (boolean, number, string or a JSON) that can be interpreted by the apps. It can be used for giving access to paid features, or to enable a feature progressively on all the cozy instances of a context. The stack computes the feature flags from several sources (in order of decreasing priority):

  • the flags set on the instance by the command cozy-stack feature flags
  • the response of the manager for GET /api/v1/flags?sets=s1,s2&context=ctx (where s1,s2 has been set via cozy-stack feature sets)
  • the flags coming from the context configuration (context.<name>.features)
  • the flags set on the context by the command cozy-stack feature ratio
  • the default value (cozy-stack feature default).

For a given flag, the stack takes the value from the source with the highest priority, and does not look at the other sources (no merge).

GET /settings/flags

This endpoint returns the computed list of feature flags for the given instance. It accepts an include parameter in the query string to see the details of how the flags were computed.

Request

GET /settings/flags HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "io.cozy.settings",
    "id": "io.cozy.settings.flags",
    "attributes": {
      "has_feature1": true,
      "has_feature2": false,
      "number_of_foos": 10,
      "bar_config": { "qux": "quux" }
    },
    "links": {
      "self": "/settings/flags"
    }
  }
}

Request

GET /settings/flags?include=source HTTP/1.1
Host: alice.example.com
Accept: application/vnd.api+json

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "io.cozy.settings",
    "id": "io.cozy.settings.flags",
    "attributes": {
      "has_feature1": true,
      "has_feature2": false,
      "number_of_foos": 10,
      "bar_config": { "qux": "quux" }
    },
    "links": {
      "self": "/settings/flags"
    }
  },
  "included": [
    {
      "type": "io.cozy.settings",
      "id": "io.cozy.settings.flags.instance",
      "attributes": {
        "number_of_foos": 10
      }
    },
    {
      "type": "io.cozy.settings",
      "id": "io.cozy.settings.flags.manager",
      "attributes": {
        "sets": ["s1", "s2"],
        "has_feature1": true,
        "number_of_foos": 5
      }
    },
    {
      "type": "io.cozy.settings",
      "id": "io.cozy.settings.flags.config",
      "attributes": {
        "number_of_foos": 2
      }
    },
    {
      "type": "io.cozy.settings",
      "id": "io.cozy.settings.flags.context",
      "attributes": {
        "has_feature2": [{ "ratio": 0.1, "value": true }],
        "bar_config": [
          { "ratio": 0.2, "value": { "qux": "quux" } },
          { "ratio": 0.8, "value": { "qux": "baz" } }
        ]
      }
    },
    {
      "type": "io.cozy.settings",
      "id": "io.cozy.settings.flags.default",
      "attributes": {
        "bar_config": { "qux": "courge" },
        "number_of_foos": 2
      }
    }
  ]
}

Permissions

To use this endpoint, an application needs a valid token, but no explicit permission is required.