When integrating with a Cyclr Marketplace you can decide whether all users access it using the same built-in Account-level “API User” (Account Marketplace - this is the typical approach), or create separate users for each in the Cyclr Account (User Marketplace).

To enable your users to view a Marketplace and install templates, you will need to have an “Integrations” button or link within your own application’s interface.

For example:

Generic Host Application

Account Marketplace

When a user clicks the Integrations button, your application server should make a Request towards the Cyclr REST API’s /v1.0/accounts/CYCLR_ACCOUNT_API_ID/marketplace endpoint to obtain a Marketplace URL. The user can then be directed to this URL in their web browser.

The CYCLR_ACCOUNT_API_ID used in the URL of the call tells Cyclr which Account to work against. If an Account doesn’t already exist with that API ID, then Cyclr will create a new Account using that value as the API ID and the AccountName value provided in your Request.

Request

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

-d '{
    "MarketplaceId": MARKETPLACE_ID,
    "AccountName": "CYCLR_ACCOUNT_NAME",
    "PartnerConnector": {
        "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/marketplace"

In the example above, replace yourCyclrInstance with your API Domain according to where your Cyclr Console is located (e.g. “api.cyclr.com”), 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
Marketplace & Account
Parameters required to identify the Marketplace to show and Account to work in
MarketplaceId The numeric ID of the Marketplace to view.
You can find this through your Cyclr Console in your web browser's address bar after pressing Edit on your Marketplace, e.g.: https://my.cyclr.uk/console/2/marketplaces/category?categoryId=10
10
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
Partner Connector
Optional parameter to install a pre-authenticated "partner connector" into the Account. Only used if an Account is created by the call.
PartnerConnector Providing your own platform's Cyclr Connector object here means your users will not be expected to authenticate against your platform during the Marketplace flow.
PartnerConnector.Name The name to give this instance of your Connector in the Account. Connector Name
PartnerConnector.Version The version of the partner connector to be installed. 1.0
PartnerConnector.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
PartnerConnector.[Properties] An array of properties required by the partner connector for successful installation. Required by some Connectors. [ {"Name": "Url", "Value": "http://customDomain.appName.com"} ]
Marketplace Display Options
Optional parameters to change the display behaviour of Marketplace
InlineOAuth Defaults to true. Set it to false if you are running Marketplace in an HTML iframe and want OAuth redirect pages to be opened in a popup. false

Response

{
    "AccountId": "CYCLR_ACCOUNT_API_ID",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "MarketplaceUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch/marketplace/10",
    "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 MarketplaceUrl will expire. 2020-01-01T12:30:00.000Z
MarketplaceUrl 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/marketplace/10
Token Marketplace URL token. lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ=

After deploying a Marketplace 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 Marketplace

When a user clicks the Integrations button, your application server should make a Request towards the Cyclr REST API’s /v1.0/users/marketplace endpoint to obtain a Marketplace 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 '{
    "MarketplaceId": MARKETPLACE_ID,
    "AccountName": "CYCLR_ACCOUNT_NAME",
    "AccountId": "CYCLR_ACCOUNT_API_ID",
    "Username": "USERNAME",
    "Password": "PASSWORD",
    "PartnerConnector": {
        "Name": "Example Connector",
        "Version": "1.0",
        "AuthValue": "XXXXXXXXXX",
        "Properties": [{"Name": "Url", "Value": "http://customDomain.appName.com"}]
    }
}' "https://yourCyclrInstance/v1.0/users/marketplace"

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
Marketplace & Account
Parameters required to identify the Marketplace to show and Account to work in
MarketplaceId The numeric ID of the Marketplace to view.
You can find this through your Cyclr Console in your web browser's address bar after pressing Edit on your Marketplace, e.g.: https://my.cyclr.uk/console/2/marketplaces/category?categoryId=10
10
AccountId API ID of the Account to work in. CustomerXYZ
AccountName (Optional) If the CYCLR_ACCOUNT_API_ID provided in the Request 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
Username Username of the user accessing the Marketplace. USERNAME
Password Password for the user. PASSWORD
Partner Connector
Optional parameter to install a pre-authenticated "partner connector" into the Account. Only used if an Account is created by the call.
PartnerConnector Providing your own platform's Cyclr Connector object here means your users will not be expected to authenticate against your platform during the Marketplace flow.
PartnerConnector.Name The name to give this instance of your Connector in the Account. Connector Name
PartnerConnector.Version The version of the partner connector to be installed. 1.0
PartnerConnector.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
PartnerConnector.[Properties] An array of properties required by the partner connector for successful installation. Required by some Connectors. [ {"Name": "Url", "Value": "http://customDomain.appName.com"} ]
Marketplace Display Options
Optional parameters to change the display behaviour of Marketplace
InlineOAuth Defaults to true. Set it to false if you are running Marketplace in an HTML iframe and want OAuth redirect pages to be opened in a popup. false

Response

{
    "AccountId": "CYCLR_ACCOUNT_API_ID",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "MarketplaceUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch/marketplace/10",
    "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 MarketplaceUrl will expire. 2020-01-01T12:30:00.000Z
MarketplaceUrl 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/marketplace/10
Token Marketplace URL token. lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ=
Tags:
Edit me