This article will guide you through installing a connector into an account. You must already have an OAuth Access Token.

Getting the connector ID

You need the ID of a connector before you can install it. You can find a connector by calling the /v1.0/connectors endpoint, this will show the connectors that are available to the account.


    GET https://yourCyclrInstance/v1.0/connectors HTTP/1.1
    Authorization: Bearer ****************************************************************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000


          "Name":"Example Connector",
          "Description":"This is an example connector.",

Installing the connector

Now that you have a connector ID, the connector can be installed by calling the /v1.0/connectors/{id}/install endpoint.

Body parameters

Parameter Description
Name The name for the installed connector
Description (Optional) Any description for the installed connector
AuthValue (Optional) Authentication value for the third party API that will be used by the connector. Provide username and password as base64 (username:password), provide API keys as plain text. OAuth can only be provided if you have your own OAuth flow implementation. To use Cyclr’s implementation see the next step.


    POST https://yourCyclrInstance/v1.0/connectors/1/install
    Authorization: Bearer ****************************************************************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    {"Name":"Example", "AuthValue":"example-api-key"}


       "Id": 1,
       "Connector":{ ... },

The connector is now installed into the account, if the connector doesn’t use OAuth you’re all done; otherwise, read on to authenticate with OAuth.

Authenticating OAuth connectors

If the connector requires an OAuth authentication to work with the third party API, you will be required to show the user a popup that will take them through the OAuth flow. First you need to get an account one time sign in token, this will be used to allow a web browser to sign in using the credentials of the Oauth token.


    POST https://yourCyclrInstance/v1.0/accounts/{AccountId}/signintoken
    Authorization: Bearer ****************************************************************
      "Username":"Username of the user the token should sign in"

NB. If said user does not exist, they will be created by this call.



Now you have a sign in token, you can “build” the URL to send the user to where they will begin the OAuth flow.

URL & Querystring

URL https://[Partner Service Domain]/connectorauth/updateaccountconnectoroauth
id This is the ID of the installed connector from the response when installing the connector
token The account sign in token
targetOrigin Specifies what the origin of the other window must be for the javascript callback event to be dispatched. If the callback message is null we will redirect to the targetOrigin
callbackMessage (Optional) Callback message to be sent to the parent window

Example built URL

https://[Partner Service Domain]/connectorauth/updateaccountconnectoroauth?id=1&token=***************************************&

When the user is sent to the built URL they will be redirected to the third party OAuth flow. On completion they will be either redirected to targetOrigin or a JavaScript message will be posted to the parent window.

Tags: embedding
Edit me