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.
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 | |
---|---|---|---|
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] |
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 | 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 | 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
{
"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 ID of account you provided in your request, or the ID of the new account if you didn’t provide one. |
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 can make the same request to the Cyclr REST API’s /v1.0/users/launch
endpoint. For more information about the endpoint, see the Interactive API reference page. To create the account, you need to pass two extra parameters in the request:
Request Parameter | Type | Description | |
---|---|---|---|
AccountId |
string | Identify the Account to use. | |
Username |
string | Identify the user’s account. | |
Password |
string | Authenticate the user’s account. |
Example 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://{CyclrAPIDomain}/v1.0/users/launch"