👍Authentication

Cherty's scheme for determining identity, and how to use it.

Identity Representation

Cherty represents identity as an ID object consisting of an identifier and an authentication method:

id_object = {id: <identifier>, method: <auth method>}

The authentication method determines the format of the id used, the type of token used to authenticate the user, and the authentication method:

method	id	Type of Token	Verified By
eth_signTypedData_v4	Ethereum Address (str)	JWT	Signature using this address
google-oauth2	Google Sub (number)	Google Access Token	Google oauth2 endpoint

This id_object scheme is extensible, allowing it to span other types of authentication methods - such as DIDs, other SSO options, email ID and different blockchain addresses - while preventing collisions. An account inherits the security properties of the authentication method used.

Currently, only the google-oauth2 method is implemented in the production version of Cherty.

An ID Object and the CID of its string are logically equivalent:

id_object <=> CID(JSON.stringify(id_object))

This is useful for expressing a public identity as a CID when id_object.id is sensitive (for example, if it's a Google sub). Note that the keys in the id_object must be alphabetized with no extra spaces, and that in general id_object -> CID is a one -> many mapping.

Trivial ID Object

If an ID object is meant to represent the public, for example for recording that a resource is publicly viewable, this ID object is used:

{id: 'public_all', method: null}

Public Account Object

In Cherty, the following information is included in a public representation of an account:

Key	Value
name	User name
profile_photo	CID of the avatar of this user. The data for this CID is public by default.
organization	The organization this user belongs to
id_object	id_object for this user, redacted if it contains sensitive information (ie. a Google Sub)
id_CID	id_CID corresponding to the non-redacted id_object. The data for this CID is not public by default.

Creating a Cherty account and API Key

Currently, the only way to create a Cherty account is to install the app on MacOS. Download the latest version from Cherty.io and right click then select Open. Install and open the app then navigate to the Account tab using the option in the upper left:

Create an account using Google SSO (more authentication options coming soon). When you have created your account, the window should look like this:

Press the Generate button in the API Key tile. This will create an API key that you can copy to a .env file to use in your project. The key is a JWT with a lifetime of 1 year. Handle this key carefully! If you store it in a .env file, make sure to include the file in .gitignore.

Endpoints

Get Account Info

https://cherty.io/api/get_account_info

Protected GET route returning info for the authenticated account

Accepts: no arguments but requires an API Token in the authorization header

Returns: JSON object with account information

{
    name: <account name, str>,
    profile_photo: <CID of account photo, str>,
    organization: <account organization, str>,
    id_cid: <CID of the primary id_object, str>,
    subscription_tier: <free/academic/pro, str>
    email: <account email, str>,
    id_object_array: <array of account ID objects, not redacted>,
}

Get Public Account Information

https://cherty.io/api/public_account_info/:id_cid

Public GET route returning publicly available information for an account

Accepts: id_cid for a user account

Returns: public account information for this user

{
  name: <account name, str>,
  profile_photo: <CID of account photo, str>,
  organization: <account organization, str>,
  id_object: <Object corresponding to this CID, redacted if sensitive>,
  id_CID: <CID of the id_object, str>
}