> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refold.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Linked Accounts

<img height="200" src="https://mintcdn.com/cobalt-55/rCTCKBbhiwGPdeWb/images/implementation/linked_account_sequence.png?fit=max&auto=format&n=rCTCKBbhiwGPdeWb&q=85&s=3369481a61037f5d74e50c386db3645c" alt="Sequence Diagram for Creating Linked Account and Session Token" data-path="images/implementation/linked_account_sequence.png" />

**Linked Accounts** refers to the end-users or customers of our users who utilize the integrations built using the Refold platform. When you create a Linked Account, you must provide a `linked_account_id`. This ID can be anything you want, but it must be unique.

Most of the time, the linked\_account\_id is an ID from your internal data model that represents a user or account in your system. For example, if you have a user in your system with the ID `account:12345`, you could use that ID as the **linked\_account\_id** for your Refold Linked Account.

Auth tokens and User configurations will be stored against the Linked account id of each user.

<Info>
  To learn more about Linked Accounts, you can refer to the Linked Accounts Guide [here](https://docs.gocobalt.io/build/basics/linked_account).
</Info>

### Using Refold API or SDK

Use the [Upsert Linked Account API](https://docs.gocobalt.io/api-reference/customer/upsert-a-linked-account) call below or the **.upsertLinkedAccount()** method of the [NodeJS SDK](https://docs.gocobalt.io/sdks/server-side-sdks/nodejs-sdk) to create or update a linked account.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.gocobalt.io/api/v2/public/linked-account \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
    "linked_account_id": "<string>",
    "name": "<string>",
    "your_app": {
      "auth_credentials":
          {
              "Authorization": "eyJvcmdfaWQiOiI2M2M5M2RhMGI0NmI3MjQzNzg1YTFlMTciLCJsaW5rZWRfYWNjb3VudF9pZCI6IjEyMzQ1Njc4IiwiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiaWF0IjoxNjg2NjQzMDg5LCJleHAiOjE2ODY5MDIyODl9"
          }
    },
    "udf": {
      "phone": "1234567890",
      "address": "121, Queen Street"
    }
  }'
  ```

  ```JavaScript NodeJS SDK theme={null}
  try{
      await Client.upsertLinkedAccount({
          linked_account_id: "user@example.com",
          name: "User2",
          udf: {
              "phone": "1234567890",
              "address": "121, Queen Street"
          },
          your_app: {
              auth_credentials:{
                  "Authorization": "eyJvcmdfaWQiOiI2M2M5M2RhMGI0NmI3MjQzNzg1YTFlMTciLCJsaW5rZWRfYWNjb3VudF9pZCI6IjEyMzQ1Njc4IiwiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiaWF0IjoxNjg2NjQzMDg5LCJleHAiOjE2ODY5MDIyODl9"
              }
          }
      })
  }catch(error){
      //Catch any error
  }
  ```
</CodeGroup>

| Param               | Required  | Type   | Description                    |
| ------------------- | --------- | ------ | ------------------------------ |
| linked\_account\_id | Mandatory | String | Unique customer identifier     |
| name                | Optional  | String | Name of the customer           |
| UDF                 | Optional  | Object | User specific preliminary data |
| your\_app           | Optional  | Object | Auth specific data             |

**your\_app Object**

| Param             | Required | Type   | Description                                                          |
| ----------------- | -------- | ------ | -------------------------------------------------------------------- |
| auth\_credentials | Optional | Object | Your customer api credentials for pushing data to your api end point |

<Info>
  your\_app is an optional param which contains details of your application associated with your account.
</Info>

The API request or Method call will respond with a JSON Object containing data about the Linked Account created/updated if successful.

```bash Response theme={null}
{
    "_id": "63cabcc596d0d10508a69bdf",
    "associated_org": "63c93da0b46b7243785a1e17",
    "account_id": "12345678",
    "environment": "test",
    "name": "Mark Wood",
    "udf": [
        {
            "key_name": "phone",
            "key_value": "1234567890",
            "_id": "64d5d69bfb78da0950f5e18f",
            "updatedAt": "2023-08-11T06:35:07.574Z",
            "createdAt": "2023-08-11T06:35:07.574Z"
        },
        {
            "key_name": "address",
            "key_value": "121, Queen Street",
            "_id": "64d5d69bfb78da0950f5e190",
            "updatedAt": "2023-08-11T06:35:07.574Z",
            "createdAt": "2023-08-11T06:35:07.574Z"
        }
    ],
    "createdAt": "2023-01-20T16:09:41.700Z",
    "updatedAt": "2023-08-11T06:35:07.574Z",
    "__v": 326
}
```

You can check the Linked Accounts present in your account by using the [List Linked Accounts API](https://docs.gocobalt.io/api-reference/customer/list-linked-accounts) Or through the **Refold Dashboard** by navigating to `Linked Accounts` in the side menu.

<img height="200" src="https://mintcdn.com/cobalt-55/rCTCKBbhiwGPdeWb/images/implementation/la.png?fit=max&auto=format&n=rCTCKBbhiwGPdeWb&q=85&s=bf354d600f9f3d41c32771efc5f7fb2d" alt="Linked Accounts on Dashboard" data-path="images/implementation/la.png" />

### Checkpoint + Next Step

<Check>
  After completing this step, you have successfully created Linked Accounts of your end-users. This will now allow your clients to make a request to the Refold APIs successfully by using their **Session Tokens** which we will create in the [next step](https://docs.gocobalt.io/implementation/integrate/get-access-token).
</Check>