To enable your users to add an integration, simply present a “Connect” button or link within your application’s UI.

For example:

Generic Host Application

When a user clicks the Connect button, your application server should make a request towards the Cyclr REST API’s /v1.0/accounts/{AccountID}/launch endpoint:

Request

curl -X POST
-H "Authorization: Bearer ${ACCESS_TOKEN}"
-H "Content-Type: application/json"
-H "Accept: application/json"

-d '{
    "partnerConnector": {
        "Name": "Connector Name",
        "Version": "1.0",
        "AuthValue": "00000000000000000000000000000000000000000",
        "Properties": [{"Name": "Url", "Value": "https://myapp.something.blah"}]
    }
}' "https://yourCyclrInstance/v1.0/accounts/0000000-0000-0000-0000-000000000000/launch"

Replace yourCyclrInstance with api.cyclr.com, api.cyclr.uk, or your own domain if your Cyclr instance is self-hosted.

You should use a non-account restricted OAuth token as the Authorization for this request.

Request parameters Description Example
Account
AccountName (Optional) If the account ID doesn't exist it will be created, you can include a name for the account otherwise the ID will be used as the name. New Cyclr Account Name
Launched Cycle Options
Optional parameters to control the initial behaviour of the launched cycle
Start Defaults to true. Set to false if you don't want the launched cycle to be started. false
RunOnce Defaults to false. Set it to true if the cycle being installed should only run once, then pause. true
Partner Connector
Optional parameter to install a pre-authenticated partner connector into the account
partnerConnector Providing your own platform's Cyclr Connector object here means your users will not be expected to authenticate against your platform during the LAUNCH flow.
partnerConnector.Name A name you wish to give this instance of your connector installed within this new or existing account. Connector Name
partnerConnector.Version The version of the partner connector to be installed. 1.0
partnerConnector.AuthValue (Optional) Authentication value for your platform connector. If your platform requires a username and password, provide a base64 encoded version of "username:password". Provide API keys as plain text. An OAuth token may also be provided here. dXNlcm5hbWU6cGFzc3dvcmQ=
or
NJ88GGgv79V79VvYFBBTHUIGu
partnerConnector.[Properties] An array of properties required by the partner connector for successful installation. This is not relevant to all connectors. [ {"Name": "Url", "Value": "http://customDomain.appName.com"} ]
LAUNCH Display Options
Optional parameters to filter the displayed templates shown in LAUNCH
Tags An array of tags that a cycle must have at least one of to appear in LAUNCH. ["CRM", "Email"]
InlineOAuth Defaults to true. Set it to false if you are running LAUNCH in an iFrame and want OAuth redirect pages to be opened in a popup. false
AutoInstall Defaults to true so that Cyclr will automatically start installation of a template if only one is returned, avoiding the need for the user to select it. Set this to false to prevent that, requiring the user to select it instead. false
SingleInstall Defaults to false so that templates are shown whether they have been installed or not. Set to true to only show templates that aren't installed in the account. true

Response

{
    "AccountId": "0000000-0000-0000-0000-000000000000",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "LaunchUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch",
    "Token": "lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ="
}
Response fields Description Example
AccountId The ID of the newly created account or the existing account you provided in your request. 0000000-0000-0000-0000-000000000000
ExpiresAtUtc Token expiry timestamp. 2020-01-01T12:30:00.000Z
LaunchUrl The URL that your user should be sent to, typically opened in a popup browser window. Once generated by Cyclr, this URL will only be valid for 5 minutes and will expire when first accessed. You should therefore direct your user to it immediately after receiving it. https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch
Token LAUNCH URL token. lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ=

After deploying LAUNCH you will see an API User in your Cyclr console. The API User has access to the account however they cannot signin to the Cyclr interface.

How to Handle Callbacks

Tags: launch
Edit me