Install Connectors

This section guides you through using the Cyclr API to install a Connector into an Account.

You must already have a Cyclr API Access Token.

Get a Connector ID #

You need the ID of a Connector before you can install it. To show a list of connectors available to the account, call the /v1.0/connectors endpoint. For more information about the endpoint, see the Interactive API reference page.

Request #

GET https://{CyclrAPIDomain}/v1.0/connectors
Authorization: Bearer {access_token}
X-Cyclr-Account: {AccountID}

Response items #

These are the values you need to include in the request when you install the connector into an account:

Parameter	Type	Description
Id	integer	The ID of the connector. Use this value as the ConnectorId when you install the connector.
Authentication.Id	string	The ID of the connector’s authentication type. Use the value of the authentication method you want to use as the AuthenticationId when you install the connector.

If Parameters.IsAccountConnectorProperty is true, you also need the following values:

Parameter	Type	Description
Parameters.TargetName	String	The name of the account connector property.
Parameters.Values	array[string]	The possible values of the account connector property.
Parameters.Id	integer	The ID of the account connector property.

Example Response #

[
  {
    "Id": 12345,
    "Name": "Example",
    "Description": "Connect securely with your Example application",
    "Status": "Approved",
    "Version": "null",
    "Icon": "Base64 image data for the connector icon",
    "AuthDescription": "null",
    "AuthType": "ApiKey", <this says deprecated in swagger, should it be null?>
    "OAuth2Type": "AuthorisationCode",<can we correct the spelling here?>
    "AuthScheme": "Authorization", 
    "Parameters": [
      {
        "IsAccountConnectorProperty": true,
        "TargetType": "Script",
        "TargetName": "isSandbox",
        "IsSensitive": false,
        "Id": 7654321,
        "Name": "Is Sandbox?",
        "Description": "Sandbox oAuth servers will not authenticate production credentials (and vice versa).",
        "IsOptional": false,
        "DataType": "Text",
        "TriggerName": "null",
        "Values": [
          "true",
          "false"
        ],
       ...
       ,
    "Authentication": [
      {
        "Id": "12abc345-1a2b-123a-1ab2-1234ab5c6d7e",
        "AuthName": "OAuth 2.0",
        "AuthDescription": "In sandbox mode, sign in to see the authorization page.",
        "AuthType": "OAuth2",
        "OAuth2Type": "AuthorisationCode",
        "AuthScheme": "null"
      }
      {
        "Id": "12abc345-1a2b-12ab-1abc-a12b3c4e567e",
        "AuthName": "API Key",
        "AuthDescription": null,
        "AuthType": "ApiKey",
        "OAuth2Type": "AuthorisationCode",
        "AuthScheme": "Authorization"
      }
    ]
  }
]

Install the Connector #

If you have the Connector ID, you can install the connector into an account. To install the connector, call the /v1.0/connectors/{id}/install endpoint. For more information about the endpoint, see the Interactive API reference page.

Request #

POST https://{CyclrAPIDomain}/v1.0/connectors/{ConnectorId}/install
Authorization: Bearer {access_token}
X-Cyclr-Account: {AccountID}

{
  "Name": "{ConnectorName}",
  "Description": "{ConnectorDescription}",
  "AuthenticationId": "{AuthenticationId}",
  "AuthValue": "{AuthValue}",
  "Properties": [
    {
      "Name": "{PropertyName}",
      "Value": "{PropertyValue}",
      "Id": {PropertyId},
    }
  ]
}

Request Parameters #

Path parameter	Type	Description
{ConnectorId}	integer	Enter the ID of the connector you want to install.

Body parameters		Type	Description
Name		string	Name the account connector
Description		string, optional	Describe the account connector.
AuthenticationId		string	Enter the ID of the authentication method you want to use. See Get connectors for more information.
AuthValue		string, optional	Basic Authentication: enter the base64 encoded value of the username and password. Oauth: enter the {access_token}. API Key: enter the {ApiKey}.
Properties		Array, optional	If Parameters.IsAccountConnectorProperty is true in the GET connectors response, include this array of values from the response.
	Name	string	Enter the Parameters.TargetName value.
	Value	array[string]	Enter a value from the options in Parameters.Values.
	Id	integer	Enter the Pararameters.Id value.

Example Response #

{
  "Id": 54321,
  "Name": "Installed Example",
  "Description": "Alex's Example account connector",
  "AuthValue": "access_token",
  "Authenticated": true,
  "Connector": {
    "Id": 12345,
    "Name": "Example",
    "Description": "Connect securely with your Example application",
    "Status": "Approved",
    "Version": "null",
    "Icon": "Base64 image data for the connector icon",
    "AuthDescription": "null",
    "AuthType": "ApiKey", <this says deprecated in swagger, should it be null?>
    "OAuth2Type": "AuthorisationCode",<can we correct the spelling here?>
    "AuthScheme": "Authorization",
    "Parameters": [...],
    ...
    ,
  }
}

Authentication #

Authentication is optional in this call because, if your customer has access to the account, they can authenticate the Connector themselves through Cyclr’s interface.

For more information on how to authenticate a specific Application Connector, see the Application Connector Guides documentation.

Alternatively, you can authenticate a Connector using the Cyclr API as described in Account and Connectors Authentication or by sending your customer a Connector Authentication Link.