Deploy LAUNCH

Overview

When integrating with LAUNCH you can decide whether all users access it using the same built-in Account-level “API User” (Account LAUNCH - this is the typical approach), or create separate users for each in the Cyclr Account (User LAUNCH).

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

Account LAUNCH

When a user clicks the Connect button, your application server should make a Request towards the Cyclr REST API’s /v1.0/accounts/CYCLR_ACCOUNT_API_ID/launch endpoint to obtain a LAUNCH URL. The user can then be directed to this URL in their web browser.

Request

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

-d '{
    "AccountName": "CYCLR_ACCOUNT_NAME",
    "ConnectorAuthentications": {
        "Name": "Example Connector",
        "Version": "1.0",
        "AuthValue": "XXXXXXXXXX",
        "Properties": [{"Name": "Url", "Value": "http://customDomain.appName.com"}]
    }
}' "https://yourCyclrInstance/v1.0/accounts/CYCLR_ACCOUNT_API_ID/launch"

In the example above, replace yourCyclrInstance with your API Domain according to where your Cyclr Console is located, or your own domain if your Cyclr instance is self-hosted.

When obtaining a Cyclr API Access Token for this call, you should not use an Account Restricted Token.

Request Parameter	Description	Example
Account
AccountName	(Optional) If the CYCLR_ACCOUNT_API_ID value provided in the Request's URL doesn't match an existing Cyclr Account, a new Account will be created using this name. If no AccountName is provided, the CYCLR_ACCOUNT_API_ID value will be used as the new Account's name.	New Cyclr Account Name
AccountDescription	(Optional) If the CYCLR_ACCOUNT_API_ID value provided in the Request's URL doesn't match an existing Cyclr account, this creates a new account with this description.	This is a LAUNCH created account
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 stop.	true
Connector Authentications Optional parameter to install pre-authenticated "partner connectors" into the Account.
[ConnectorAuthentications]	Providing your own platform's Cyclr Connector objects here means your users will not be expected to authenticate against your platform during the LAUNCH flow.
[ConnectorAuthentications].Name	The name to give this instance of your Connector in the Account.	Connector Name
[ConnectorAuthentications].Version	The version of the partner connector to be installed.	1.0
[ConnectorAuthentications].AuthenticationId	The ID of the authentication method you want this instance of your Connector to use. If the Connector only supports one form of authentication, this value becomes optional.	0000000-0000-0000-0000-000000000000
[ConnectorAuthentications].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
[ConnectorAuthentications].[Properties]	An array of properties required by the partner connector for successful installation. Required by some Connectors.	[ {"Name": "Url", "Value": "http://customDomain.appName.com"} ]
LAUNCH Options
Tags	An array of Tags that a Cycle must have at least one of to appear through LAUNCH.	["CRM", "Email"]
InlineOAuth	Defaults to false except for partners that existed before Aug 2022 where default is true. Set it to false if you are running LAUNCH in an HTML 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 haven't already been installed in the Account.	true
CompleteParameter	A value to pass through to the final page of the LAUNCH flow.
Wizard	Defaults to false. Whether Cyclr displays mappings to the user as a step-by-step wizard (true), or all at once as a single form (false).	true
DisplayDescriptions	Defaults to false. Whether template descriptions should be displayed to the user on the cycle selection screen.	true

Response

{
    "AccountId": "CYCLR_ACCOUNT_API_ID",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "LaunchUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch",
    "Token": "lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ="
}

Response Field	Description	Example Value
AccountId	The ID of the newly created account, or the existing account you provided in your Request.	CustomerXYZ
ExpiresAtUtc	When the Token and LAUNCH URL will expire.	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

User LAUNCH

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

A new user will be created if the don’t already exist.

Request

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

-d '{
    "AccountId": "0000000-0000-0000-0000-000000000000",
    "Username": "example",
    "Password": "P4$$w0rd",
    "ConnectorAuthentications": {
        "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 non-account restricted OAuth token as the Authorization for this request.

Request parameters	Description	Example
Account
AccountId	ID of the account.	0000000-0000-0000-0000-000000000000
Username	Username of the user the LAUNCH is for.	example
Password	The users password.	P4$$w0rd
AccountName	(Optional) If the account doesn't exist, this creates one. You can include a name for the account, otherwise it uses the ID as the name.	New Cyclr Account Name
AccountDescription	(Optional) If the account doesn't exist, this request creates a new account and you can include a description.	This is a LAUNCH created account
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
Connector Authentications Optional parameter to install pre-authenticated "partner connectors" into the Account.
[ConnectorAuthentications]	Providing your own platform's Cyclr Connector objects here means your users will not be expected to authenticate against your platform during the LAUNCH flow.
[ConnectorAuthentications].Name	The name to give this instance of your Connector in the Account.	Connector Name
[ConnectorAuthentications].Version	The version of the partner connector to be installed.	1.0
[ConnectorAuthentications].AuthenticationId	The ID of the authentication method you want this instance of your Connector to use. If the Connector only supports one form of authentication, this value becomes optional.	0000000-0000-0000-0000-000000000000
[ConnectorAuthentications].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
[ConnectorAuthentications].[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 false except for partners that existed before Aug 2022 where default is 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
CompleteParameter	A value to pass through to the final page of the LAUNCH flow.
Wizard	Defaults to false. Whether Cyclr displays mappings to the user as a step-by-step wizard (true), or all at once as a single form (false).	true
DisplayDescriptions	Defaults to false. Whether Cyclr displays template descriptions to the user.	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=

How to Handle Callbacks

In This Article

Deploy LAUNCH

Overview

Account LAUNCH

Request

Response

User LAUNCH

Request

Response