# Authentication

## Identity Representation

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

```javascript
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.&#x20;

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

<pre class="language-javascript"><code class="lang-javascript"><strong>id_object &#x3C;=> CID(JSON.stringify(id_object))
</strong></code></pre>

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:

```javascript
{id: 'public_all', method: null}
```

### Public Account Object

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

<table><thead><tr><th width="166">Key</th><th>Value</th></tr></thead><tbody><tr><td>name</td><td>User name</td></tr><tr><td>profile_photo</td><td>CID of the avatar of this user. The data for this CID is public by default.</td></tr><tr><td>organization</td><td>The organization this user belongs to</td></tr><tr><td>id_object</td><td>id_object for this user, redacted if it contains sensitive information (ie. a Google Sub)</td></tr><tr><td>id_CID</td><td>id_CID corresponding to the non-redacted id_object. The data for this CID is not public by default.</td></tr></tbody></table>

## 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](https://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:

<figure><img src="/files/jLogIiB9xv6Sbak2QZEn" alt="" width="283"><figcaption></figcaption></figure>

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

<figure><img src="/files/qzrAhVUwokN8dfHjSLE4" alt="" width="333"><figcaption></figcaption></figure>

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

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

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

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

```json
{
  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>
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cherty.io/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.