Skip to main content
Skip table of contents

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 the Marketplace.

  • A User LAUNCH needs you to create separate user profiles for each user in your 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"

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.