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 Cyclr REST API’s /users/launch method:

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

-d '{
    "Username": "user@example.com", 
    "Password": "password",
    "AccountId": "0000000-0000-0000-0000-000000000000",
    "partnerConnector": {
        "Name": "Connector Name",
        "Version": "1.0",
        "AuthValue": "00000000000000000000000000000000000000000",
        "Properties": [{"Name": "Url", "Value": "https://myapp.something.blah"}]
    }
}' "https://yourCyclrInstance/v1.0/users/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 Cyclr Partner OAuth token as the Bearer token in this request.

Request parameters Description Example
Username The name of the Cyclr account (and Cycrl user) to install this integration in, or to create if such an account (and user) does not already exist. user@example.com
Password The password to assign to the new Cyclr user account, if created. If you do not intend your end users to access the Cyclr application directly, this password can be an obscure value known only to your app. sdkjgnjg35d
AccountName If your user doesn't already have an account within Cyclr, specify the name of the account to create here. New Cyclr Account Name
AccountId If your user already has an account within Cyclr, specify the Id of that account to have the new integration installed there. If this is not provided, a new Cyclr account will be created. 0000000-0000-0000-0000-000000000000
partnerConnector (Optional) Providing the platform connector object here means your user will not be expected to authenticate against your own 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 users a username and password, provide as base64 encoded version of username:password Provide API keys as plain text. An OAuth token may also be provided here. dXNlcm5hbWU6cGFzc3dvcmQ= or NJ88GGgv79V79VvYFBBTHUIGYBGY3434345545UYu or NJ88GGgv79V79VvYFBBTHUIGYBGY3434345545UYu
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"} ]
RunOnce (Optional) Defaults to false. Set it to true if the cycle being installed should only run once, then pause. true
Tags (Optional) An array of tags that a cycle must have at least one of to appear in LAUNCH. ["CRM", "Email"]
InlineOAuth (Optional) 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 (Optional) 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 (Optional) 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": "17/01/2018 12:11:22",
    "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. 17/01/2018 12:11:22
LaunchUrl The URL that your user should be sent to, typically opened in a popup browser window. Once generated by Cyclr, this URL will be valid for 5-minutes only and for a single request only, so you user should be passed here immediately and one time only. https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch
Token LAUNCH URL token. lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ=

How to Handle Callbacks

Tags: launch
Edit me