Table of contents

Cozy Accounts doctype

The io.cozy.accounts doctype stores authentification informations used by konnectors to connect to external services or API.

Accounts can be managed in Cozy-Home (via Harvest). They are generally associated to a io.cozy.triggers document.

io.cozy.accounts attributes are:

About the name of the account

We need a name for the account displayed to the user in harvest and for cozy-stack to create the associated folder if needed. If missing, harvest will determine the value of the identifier attribute based on the following rules:

  1. a konnector’s manifest field name if it has the role: "identifier" attribute
  2. login if auth.login is defined
  3. identifier if auth.identifier is defined
  4. new_identifier if auth.new_identifier is defined
  5. email if auth.email is defined

If the identifier attribute is defined, the account name will be chosen based on these rules:

  1. auth[identifer] if defined (we use the value of the identifier attibute here)
  2. _id

For banking connectors, the identifier attribute contains the string identifier so, the name of the account is the value of auth.identifier.

Attributes

mutedErrors

This field is used to keep track of konnector errors that have been muted by the user and shouldn’t be featured in the UI anymore.

{
  "account_type": "example-konnector",
  "auth": {
    "identifier": "0000000000"
  },
  "mutedErrors": [
    {
      "type": "LOGIN_FAILED",
      "mutedAt": "2019-12-01T00:48:01.404911778Z"
    }
  ]
}

Relationships

parent

An account may have a parent relationship. It is used to indicate that this accounts depends on another one. Generally, the konnector should be able to handle by itself this kind of relationshiop, like querying the database to get the information it needs. A parent relationship is aimed to be an account overriden by the account it is linked to, but it can also be use as an aggregator account. See Cozy-stack documentation about aggregator accounts.

{
  "relationships": {
    "parent": {
      "data": {
        "_id": "aggregator-service-account",
        "_type": "io.cozy.accounts"
      }
    }
  }
}

Vault Cipher vaultCipher

An account can be synced in a password manager. In that case, the vaultCipher relationship can be used to store data used to synchronize the document with the remote endpoint.

{
  "relationships": {
    "vaultCipher": {
      "data": {
        "_id": "123abc",
        "_type": "com.bitwarden.ciphers",
        "_protocol": "bitwarden"
      }
    }
  }
}

Contracts contracts

When the connector brings contracts (in the case of banking connectors, contracts means individual banking accounts), the connector stores information on the contracts in the contracts relationship. Relationship items store extra information in the metadata key of the relationship item.

{
  "relationships": {
    "contracts": {
      "data": [
        {
          "_id": "77b662b903f1bac7a78cf8cc12806479",
          "_type": "io.cozy.bank.accounts",
          "metadata": {
            "deletedByVendor": false,
            "imported": true,
            "label": "Compte chèque",
            "vendorId": "1337"
          }
        },
        {
          "_id": "07c731e303e0d50a5407b7eca9389890",
          "_type": "io.cozy.bank.accounts",
          "metadata": {
            "deletedByVendor": false,
            "imported": false,
            "label": "Assurance Vie",
            "vendorId": "1338"
          }
        }
      ]
    }
  }
}

Examples

Freemobile (regular connector, with current deprecation)

{
  "_id": "c8ae8c7e5554f223816c71a066f1a621",
  "id": "c8ae8c7e5554f223816c71a066f1a621",
  "account_type": "freemobile",
  "auth": {
    "credentials_encrypted": "aaDtwWSWsdpbbbbbbbbbbbbbbOzp...n4Y8c=",
    "login": "0612345678"
  },
  "defaultFolderPath": "/Administratif/Free Mobile/0612345678",
  "identifier": "login",
  "state": "LOGIN_SUCCESS",
  "cozyMetadata": {
    "createdAt": "2022-11-15T16:12:10.736Z",
    "metadataVersion": 1,
    "updatedAt": "2022-11-15T16:32:58.617Z",
    "updatedByApps": [
      {
        "date": "2022-11-15T16:32:58.617Z"
      }
    ]
  }
}

Caisse d’Épargne (Budget Insights connector)

The connectors based on Budget Insight API are storing specific informations into data attribute.

{
  "account_type": "caissedepargne1",
  "auth": {
    "bankIds": ["1"]
  },
  "data": {
    "auth": {
      "bi": {
        "connId": 1556
      }
    }
  }
}