> For the complete documentation index, see [llms.txt](https://docs.moojo.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moojo.id/user-credentials/define-and-add-new-credentials.md).

# Define & add new credentials

## The Credential Schema Structure

Before attesting a credential to a user, you must first define its schema.

A credential consists of two parts: a **slug name**, which serves as a unique identifier, and a **list of fields** with their corresponding values.

<table><thead><tr><th width="132">Property</th><th width="118">Type</th><th width="112" data-type="checkbox">Required?</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><strong>slug</strong></td><td>String</td><td>true</td><td>A unique and descriptive name for the credential schema.</td><td>'monthly_expense'</td></tr><tr><td><strong>name</strong></td><td>String</td><td>false</td><td>A short, human-readable name for the credential</td><td>'Monthly expense per category'</td></tr><tr><td><strong>description</strong></td><td>String</td><td>false</td><td>A detailed explanation of the credential, including how it’s calculated and how to interpret it. This helps make the credential self-explanatory.</td><td>'The average financial expenses over the 90 days preceding the credential’s generation date, calculated using data from Plaid. This includes transactions from both credit cards and bank accounts'</td></tr><tr><td><strong>codeUrl</strong></td><td>String</td><td>false</td><td>A direct URL to the code snippet used to calculate this credential. This promotes transparency and allows others to verify how the credential was generated. The link can point to a GitHub repository or any other trusted source provider</td><td></td></tr><tr><td><strong>fields</strong></td><td>JSON</td><td>false</td><td>A payload for the credential, which includes a list of fields and their corresponding values.</td><td>{<br>  "name": "expense",<br>  "type": "uint",<br>  "description": "the dollar value of the average expense"<br>}</td></tr></tbody></table>

### Credential field types

| Type   | Example               |
| ------ | --------------------- |
| uint   | 130; 5400             |
| string | 'USD'; 'Low Fat Milk' |

{% hint style="warning" %}
**Credential Limit**&#x20;

Each credential schema can contain **up to 12 fields**.
{% endhint %}

## Define a New Credential Schema

<mark style="color:green;">`POST`</mark> `/api.moojo.id/define-credential`

**Headers**

| Name         | Value                               |
| ------------ | ----------------------------------- |
| Content-Type | `application/json`                  |
| x-api-key    | `Your API KEY as provided by Moojo` |

**Body**

| Name               | Type             | Description                              |
| ------------------ | ---------------- | ---------------------------------------- |
| `slug`             | string           | A unique name of the credential's scheme |
| `fieldDefinitions` | Array of objects | An array of fields definition            |

**Request example**

{% tabs %}
{% tab title="body" %}
{% code overflow="wrap" %}

```json
{
    "slug": "groceries-expenses",
    "name": "Groceries Expenses",
    "description": "The user’s grocery spending, calculated as the average over the 90 days preceding the credential’s generation date. Based on data provided by MasterCard.",
    "codeUrl": "https://github.com/my-code-url"
    "fieldDefinitions": [  {"name":"monthly-spend",
                            "type":"uint",
                            "description":"The average monthly expense"},
                           {"name":"currency",
                            "type":"string",
                            "description":"3-digit currency code"}
                         ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Response example**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "traceId": "b1adc9d8-1bb2-43c2-98d7-2ce6573f8b63",
    "data": {
        "credentialDefinition": {
            "slug": "groceries-expenses",
            "name": "Groceries Expenses",
            "description": "The user’s grocery spending, calculated as the average over the 90 days preceding the credential’s generation date. Based on data provided by MasterCard.",
            "codeUrl": "https://github.com/my-code-url"
            "ownerAddress": "0x8b689df125676bafa90b923edc4a92a2ea4b0000"
            "fieldDefinitions": [  {"name":"monthly-spend",
                                    "type":"uint",
                                    "description":"The average monthly expense"},
                                   {"name":"currency",
                                    "type":"string",
                                    "description":"3-digit currency code"}
                                 ]
         }
    }
}
```

{% endtab %}
{% endtabs %}

## Add a Credential to a User

After defining a credential schema, you can begin adding credentials based on it to users

<mark style="color:green;">`POST`</mark> `/api.moojo.id/user/add-credential`

**Headers**

| Name         | Value                               |
| ------------ | ----------------------------------- |
| Content-Type | `application/json`                  |
| x-api-key    | `Your API KEY as provided by Moojo` |

**Body**

| Name           | Type   | Description                                                                                                                  |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `publicUserId` | string | The publicUserId of the user receiving the credential. This ID can be found in the response of the user authentication call. |
| `slug`         | string | The unique name of the credential to be added, as defined by the scheme.                                                     |
| `fields`       | Object | An object containing all fields defined in the scheme along with their corresponding values. See the example below.          |

**Request example**

{% tabs %}
{% tab title="body" %}
{% code overflow="wrap" %}

```json
{
  "publicUserId": "{{publicUserId}}",
  "slug": "groceries-expenses",
  "fields": {
    "monthly-spend": 300,
    "currency": "USD"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Response example**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "traceId": "de665302-fb90-4742-85ca-fd399d681fd7",
    "data": {
        "attestedCredential": {
            "createdAt": 1739442337986,
            "issuerAddress": "0x8b689df125676bafa90b923edc4a92a2ea000000",
            "recipientAddress": "0x4e8aefeffaad79fcc520b1c46d09d13ae4000000",
            "slug": "groceries-expenses",
            "fields": {
                "monthly-spend": 300,
                "currency": "USD"
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}