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.
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= |