Linked Accounts refers to the end-users or customers of our users who utilize the integrations built using the Cobalt 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 Cobalt Linked Account.

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

To learn more about Linked Accounts, you can refer to the Linked Accounts Guide here.

You can create Linked Accounts programatically by using Cobalt APIs or SDK methods.

Using Cobalt API or SDK

Use the Upsert Linked Account API call below or the .upsertLinkedAccount() method of the NodeJS SDK to create or update a linked account.

curl --request PUT \
  --url \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "linked_account_id": "<string>",
  "name": "<string>",
  "your_app": {
    "app_id": "64da0b57c9ae95561bb0a2ea",
            "Authorization": "eyJvcmdfaWQiOiI2M2M5M2RhMGI0NmI3MjQzNzg1YTFlMTciLCJsaW5rZWRfYWNjb3VudF9pZCI6IjEyMzQ1Njc4IiwiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiaWF0IjoxNjg2NjQzMDg5LCJleHAiOjE2ODY5MDIyODl9"
  "udf": {
    "phone": "1234567890",
    "address": "121, Queen Street"
linked_account_idMandatoryStringUnique customer identifier
nameOptionalStringName of the customer
UDFOptionalObjectUser specific preliminary data
your_appOptionalObjectAuth specific data

your_app Object

app_idMandatoryStringApplication Id of your default app
auth_credentialsOptionalObjectYour customer api credentials for pushing data to your api end point

your_app is an optional param which contains details of your application associated with your account.

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

    "_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 Or through the Cobalt Dashboard by navigating to Linked Accounts in the side menu.

Linked Accounts on Dashboard

Checkpoint + Next Step

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 Cobalt APIs successfully by using their Session Tokens which we will create in the next step.