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"