Session-based authentication (cookies)

Some APIs use cookie-based authentication. Once authenticated — usually by sending a username and password to a login endpoint — the API returns a session cookie, which must then be included in every subsequent request.

To configure cookie authentication, add an authentication component with type: "cookie". You collect the user's credentials through user inputs, define a login request that returns the cookie, and list which cookies to store. The stored cookies are then referenced in your requests.

How cookie authentication works

1. The user provides their credentials (typically a username and password) through user inputs.
2. Supermetrics sends a login request, defined under the cookie object, to the data source's authentication endpoint.
3. The cookies you list are captured from the response and stored in the Data source user.
4. The stored cookies are included in subsequent requests through a Cookie header.

Template cookie authentication configuration

Below you can find a template configuration that you can fill in with your own information for an easier start:

{
  "authentication": {
    "type": "cookie",
    "description": "[Description shown to users during the authentication flow]",
    "userInputs": [
      {
        "id": "username",
        "label": "Username",
        "type": "text"
      },
      {
        "id": "password",
        "label": "Password",
        "type": "password"
      }
    ],
    "cookie": {
      "cookies": [
        {
          "value": "[name of the cookie to store]"
        }
      ],
      "request": {
        "method": "POST",
        "url": "[URL to the login endpoint]",
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "type": "json",
          "content": {
            "[username field]": "{{inputs.username}}",
            "[password field]": "{{secrets.password}}"
          }
        }
      }
    }
  },
  "secrets": {
    "items": [
      {
        "id": "password",
        "classification": "secret",
        "source": "userInput",
        "value": "password"
      }
    ]
  }
}

The cookie object requires two properties:

Configuring cookie authentication

We'll walk through configuring cookie authentication using the RTB House API as an example. The user connects with the same username and password they use for the RTB House dashboard.

User inputs

First, collect the credentials the login endpoint requires:

"userInputs": [
  {
    "id": "username",
    "label": "Username",
    "type": "text"
  },
  {
    "id": "password",
    "label": "Password",
    "type": "password"
  }
]

Registering the password as a secret

The password is sensitive, so we register it as a secret and reference it in the login request with the {{secrets.password}} placeholder rather than {{inputs.password}}. Define the secret at the connector root, with source: "userInput" and value set to the id of the password input field:

{
  "secrets": {
    "items": [
      {
        "id": "password",
        "classification": "secret",
        "source": "userInput",
        "value": "password"
      }
    ]
  }
}

Cookie object

Next, define the cookie object. The request authenticates the user by sending their credentials to the login endpoint, and cookies lists the cookie to capture from the response — in this case, session. The password is referenced through the secret registered above:

"cookie": {
  "cookies": [
    {
      "value": "session"
    }
  ],
  "request": {
    "method": "POST",
    "url": "https://api.panel.rtbhouse.com/v5/auth/login",
    "config": {
      "cache": {
        "useCache": false
      }
    },
    "headers": [
      {
        "name": "Accept",
        "value": "application/json"
      },
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ],
    "body": {
      "type": "json",
      "content": {
        "login": "{{inputs.username}}",
        "password": "{{secrets.password}}"
      }
    }
  }
}

Storing the cookie in Data source user

The captured cookie is stored in the Data source user so it can be used in later requests. Store the cookie as a property with source: "cookie" and value set to the cookie name.

It's also good practice to store the username, so the connection can be re-authenticated if the cookie expires. The password doesn't need to be stored here — it's held in the secret registered earlier, which resolves during re-authentication:

{
  "dataSourceUser": {
    "userInfo": {
      "id": {
        "source": "userInput",
        "value": "username"
      },
      "label": {
        "source": "userInput",
        "value": "username"
      },
      "properties": [
        {
          "id": "cookie",
          "source": "cookie",
          "value": "session"
        },
        {
          "id": "username",
          "source": "userInput",
          "value": "username"
        }
      ]
    }
  }
}

Full configuration

Putting the user inputs, the cookie object, the secret, and the Data source user together, the complete configuration looks like this:

{
  "authentication": {
    "type": "cookie",
    "description": "Enter your RTB House username and password",
    "userInputs": [
      {
        "id": "username",
        "label": "Username",
        "type": "text"
      },
      {
        "id": "password",
        "label": "Password",
        "type": "password"
      }
    ],
    "cookie": {
      "cookies": [
        {
          "value": "session"
        }
      ],
      "request": {
        "method": "POST",
        "url": "https://api.panel.rtbhouse.com/v5/auth/login",
        "config": {
          "cache": {
            "useCache": false
          }
        },
        "headers": [
          {
            "name": "Accept",
            "value": "application/json"
          },
          {
            "name": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "type": "json",
          "content": {
            "login": "{{inputs.username}}",
            "password": "{{secrets.password}}"
          }
        }
      }
    }
  },
  "secrets": {
    "items": [
      {
        "id": "password",
        "classification": "secret",
        "source": "userInput",
        "value": "password"
      }
    ]
  },
  "dataSourceUser": {
    "userInfo": {
      "id": {
        "source": "userInput",
        "value": "username"
      },
      "label": {
        "source": "userInput",
        "value": "username"
      },
      "properties": [
        {
          "id": "cookie",
          "source": "cookie",
          "value": "session"
        },
        {
          "id": "username",
          "source": "userInput",
          "value": "username"
        }
      ]
    }
  }
}

Using the cookie in requests

Include the stored cookie in your requests by adding a Cookie header, referencing the stored value with the {{user.properties.<id>}} placeholder. With the configuration above, the cookie is available as {{user.properties.cookie}}:

"request": {
  "method": "GET",
  "url": "https://api.panel.rtbhouse.com/v5/...",
  "headers": [
    {
      "name": "Cookie",
      "value": "session={{user.properties.cookie}}"
    }
  ],
  "response": {
    "type": "JSON",
    "dataRows": {
      "source": "jsonPath",
      "value": "$.data.*"
    }
  }
}