Introduction to Connector Authentication

This article explains how to authenticate a Connector using Cyclr’s API, instead of through the interface or by using the embedding features. Using the Cyclr API for this is often only needed when automating setup, or for custom use-cases.

Cyclr supports several types of authentications in Connectors, these being the main 3:

AuthType	Description
API Key	Your user will provide an API Key from the third party application that gives access to the third party API.
HTTP Basic	Your user will provide a username and password to access the third Party API.
OAuth	Your user will be taken through an OAuth flow which will generate an access token that’s returned to Cyclr which is then used to access the third party API.

For each Connector requiring authentication, take your user through the appropriate flow.

Setting up an Account Connector through Cyclr’s API can sometimes be involved, depending on the authentication the Connector uses and any additional properties that must be set.

A helpful way to understand how to authenticate a particular Connector is by installing and authenticating one within an Account through Cyclr’s interface, which easily guides you through the process. You can then identify how the options are displayed to the user and how each effects the actual values stored on the Account Connector itself.

You can retrieve the current state of an Account Connector using this Cyclr API endpoint to see which properties are used and how the authentication is stored:
GET /v1.0/account/connectors/{id}

Checking the Authentication Type #

To check the Authentication Type that an installed Account Connector uses, make the following call:

Request #

GET /v1.0/account/connectors/{id}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

Response #

    {
        "Id": XXXX,
        "Name": "Pipedrive",
        "Description": null,
        "AuthValue": null,
        "Authenticated": false,
        "Connector": {
            "Id": XXXX,
            "Name": "Pipedrive",
            "Status": "Approved",
            "Version": "1.0",
            "Icon": null,
            "AuthDescription": null,
            "AuthType": "ApiKey",
            "OAuth2Type": "Unknown",
            "AuthScheme": null,
            "Parameters": []
        },
        "IsPartnerIntegrationConnector": false,
        "Properties": [],
        "CustomFields": []
    }

In this example, the AuthType for this Account Connector is “ApiKey“.

The Response also confirms that the Account Connector is not considered to have been authenticated yet, showing "Authenticated": false.

Some Connectors have multiple Authentication Types defined on them.

Account Connector Properties #

Before beginning the authentication process, you should set the values of any Properties on the Account Connector that aren’t marked as Optional as they are typically required before authentication can proceed.

To identify what they are, look in the Connector section you receive when making the Cyclr API call above for items within the Parameters property which have IsAccountConnectorProperty: true and IsOptional: false.

You can then create Account Connector Properties with matching Name properties for each of those Parameter’s TargetName properties. Those strings are case-sensitive.

{
    ...
    "Connector": {
        "Id": 0,
        "Name": "Pipedrive",
        "AuthDescription": null,
        "AuthType": "ApiKey",
        "OAuth2Type": "Unknown",
        "AuthScheme": null,
        "Parameters": [
            {
                "IsAccountConnectorProperty": true,
                "TargetType": "Script",
                "TargetName": "isSandbox",
                "Name": "Is Sandbox?",
                "IsOptional": false,
                "DataType": "Text"
            },
            {
                "IsAccountConnectorProperty": true,
                "TargetType": "Script",
                "TargetName": "CustomFieldsOptions",
                "Name": "Disable Adding Options to Custom Fields?",
                "IsOptional": true,
                "DataType": "Text"
            }
        ],
        ...
    }
    ...
}

If you’re embedding Cyclr within your own web application, you may need to provide some user interface of your own to obtain values for some Parameters from the user, to then set through Cyclr’s API.

You can call the POST /v1.0/account/connectors/{accountConnectorId}/properties endpoint for each of the Account Connector Properties you need to create on your Account Connector, or call the PUT /v1.0/account/connectors/{id} endpoint and provide only Properties to add and set multiple in one call.

Example of setting multiple Account Connector Properties by updating the Account Connector:

PUT /v1.0/account/connectors/XXXX

{
  "Properties": [
    {
      "Name": "isSandbox",
      "Value": true
    },
    {
      "Name": "CustomFieldsOptions",
      "Value": false
    }
  ]
}

The Account Connector should then be ready to authenticate.

API Key Authentication
HTTP Basic Authentication
OAuth Authentication
Changing Authentication Type