Deploy LAUNCH

Overview

When you provide your integrations with LAUNCH, there are two ways you can give access to your users:

An Account LAUNCH has a built-in API account that all users use to access it.
A User LAUNCH needs you to create separate user profiles for each user in the Cyclr account.

To allow your users to access LAUNCH, you need to provide your users with a link or button within your application that directs your user to the LAUNCH URL.

Deploy LAUNCH request

You need to set up the link that you provide so that your application makes a request to the Cyclr REST API /v1.0/accounts/CYCLR_ACCOUNT_API_ID/launch endpoint in order to obtain a LAUNCH URL. This directs your user to that URL when they select the link to your integrations. For more information about the endpoint, see the Interactive API reference page.

When you obtain a Cyclr API Access Token for this call, don’t use an Account Restricted Token.

Example request

Replace {CyclrAPIDomain} with your API Domain according to the location of your Cyclr console, or your own domain if your Cyclr instance is self-hosted.

CODE

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://{CyclrAPIDomain}/v1.0/accounts/{CYCLR_ACCOUNT_API_ID}/launch"

Request parameters

Request Parameter	Type	Description
`CYCLR_ACCOUNT_API_ID`	string	API ID of the account to use. If an account with this API ID doesn’t exist, Cyclr creates a new account using this value.
Account
`AccountName`	string, optional.	If the `CYCLR_ACCOUNT_API_ID` value in the request's URL doesn't match an existing Cyclr Account, Cyclr creates a new Account with this name. If you don’t provide an account name, Cyclr uses the `CYCLR_ACCOUNT_API_ID` value as the new Account's name.
`AccountDescription`	string, optional.	If the `CYCLR_ACCOUNT_API_ID` value from the request URL doesn't match an existing Cyclr account, Cyclr creates a new account with this description.
Launched Cycle Options Optional parameters to control the initial behavior of the launched Cycle.
`Start`	boolean	Defaults to `true`. Set the parameter to `false` if you don't want to start the installed integration.
`RunOnce`	boolean	Defaults to `false`. Set the parameter to `true` if you want the installed integration to only run once.
Connector Authentications Optional parameter to install pre-authenticated "partner connectors" into the Account.
`[ConnectorAuthentications]`	array	Provide your own platform's Cyclr Connector objects so that your users don’t need to authenticate against your platform during the LAUNCH flow.
`[ConnectorAuthentications].Name`	string	Name this instance of your connector in the account to help identify it.
`[ConnectorAuthentications].Version`	string	Specify the version of the connector you want the user to install.
`[ConnectorAuthentications].AuthenticationId`	string	Provide 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 is optional.
`[ConnectorAuthentications].AuthValue`	string, optional.	(Optional) Provide the authentication value for your platform connector. If your platform requires a username and password, provide a base64 encoded version of `username:password`. You can also provide OAuth tokens and API keys as plain text.
`[ConnectorAuthentications].[Properties]`	array, optional	Provide an array of any properties that the partner connector requires for successful installation. Note: Not all connectors require this array.
LAUNCH Options
`Tags`	array, optional	Provide an array of tags to identify the integration. Am integration needs at least one tag to appear through LAUNCH.
`InlineOAuth`	boolean	This parameter defaults to `false` except for partners that existed before Aug 2022, where the default is `true`. Set the parameter to `false` if you run LAUNCH in an HTML iframe and want to open OAuth redirect pages in a popup.
`AutoInstall`	boolean	This parameter defaults to `true`, so Cyclr automatically starts installing a template if only one is returned. This means that your user doesn’t need to select it if it’s the only option.
`SingleInstall`	boolean	This parameter defaults to `false` so that LAUNCH shows the user all templates, even if they are already installed. Set the parameter to `true` to only show templates that the user hasn’t installed before.
`CompleteParameter`	string	Provide a value to pass through to the final page of the LAUNCH flow.
`Wizard`	boolean	This parameter defaults to `false`. Set to `true` to display mappings to the user as a step-by-step wizard, or `false` to show them all at once as a single form.
`DisplayDescriptions`	boolean	This parameter defaults to `false`. Set the parameter to `true` to display template descriptions to the user on the cycle selection screen.

Deploy LAUNCH response

CODE

{
    "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 parameters

Response Field	Description
`AccountId`	The API ID of the account you provided in your request, or the API ID of the new account if one was created.
`ExpiresAtUtc`	The date and time that the token and LAUNCH URL expires.
`LaunchUrl`	The URL that you can send your user to, typically in a popup browser window. When Cyclr generates the URL, it’s only valid for 5 minutes and expires after it’s first accessed. You can therefore direct your user to the URL immediately after you recieve it.

When you deploy LAUNCH, your console displays an API User. The user has access to the account, but can’t sign in to the console themselves.

Deploy user LAUNCH

To deploy a user LAUNCH, you make a similar request to the Cyclr REST API’s /v1.0/users/launch endpoint.

For more information about the endpoint, see the Interactive API reference page.

There are 3 additional properties to use in this Request:

Request Parameter

Type

Description

AccountId

string

The Cyclr Account API ID of the Account to use.

If it doesn’t already exist, a new Account will be created.

Username

string

Identifies the user.

If the user doesn’t already exist, a new User will be created with these details.

Password

string

Password of the user.

Example request

CODE

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

-d '{
    "AccountId": "{CYCLR_ACCOUNT_API_ID}",
    "Username": "ExampleUser",
    "Password": "P4$$w0rd",
	"ConnectorAuthentications": [
		{
			"Name": "Example Connector",
			"Version": "1.0",
			"AuthValue": "XXXXXXXXXX",
			"Properties": [
				{
					"Name": "Url",
					"Value": "http://customDomain.appName.com"
				}
			]
		}
	]
}' "https://{CyclrAPIDomain}/v1.0/users/launch"