When integrating with a Marketplace you can have all users make use of the built in account API User (Account Marketplace) or create & use users 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 application’s UI.

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/{AccountId}/marketplace endpoint:

Request

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

-d '{
    "MarketplaceId": 123,
    "PartnerConnector": {
        "Name": "Connector Name",
        "Version": "1.0",
        "AuthValue": "00000000000000000000000000000000000000000",
        "Properties": [{"Name": "Url", "Value": "https://myapp.something.blah"}]
    }
}' "https://yourCyclrInstance/v1.0/accounts/0000000-0000-0000-0000-000000000000/marketplace"

In the examples above, replace yourCyclrInstance with api.cyclr.com, api.cyclr.uk, or your own domain if your Cyclr instance is self-hosted.

You should use a non-account restricted OAuth token as the Authorization for this request.

Request Parameter Description Example
Marketplace & Account
Parameters required to identify the Marketplace to show and account name
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=27
123
AccountName (Optional) If the account ID doesn't exist it will be created, you can include a name for the account otherwise the ID will be used as the 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.
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 A name you wish to give this instance of your Connector installed within the new or existing 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. This is not relevant to all 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": "0000000-0000-0000-0000-000000000000",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "MarketplaceUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch/marketplace/1",
    "Token": "lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ="
}
Response Field Description Example Value
AccountId The ID of the newly created account, or the existing account you provided in your request. 0000000-0000-0000-0000-000000000000
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/1
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:

Request

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

-d '{
    "MarketplaceId": 123,
    "AccountId": "0000000-0000-0000-0000-000000000000",
    "Username": "example",
    "Password": "P4$$w0rd",
    "PartnerConnector": {
        "Name": "Connector Name",
        "Version": "1.0",
        "AuthValue": "00000000000000000000000000000000000000000",
        "Properties": [{"Name": "Url", "Value": "https://myapp.something.blah"}]
    }
}' "https://yourCyclrInstance/v1.0/users/marketplace"

In the examples above, replace yourCyclrInstance with api.cyclr.com, api.cyclr.uk, or your own domain if your Cyclr instance is self-hosted.

You should use a non-account restricted OAuth token as the Authorization for this request.

Request Parameter Description Example
Marketplace & Account
Parameters required to identify the Marketplace to show and account name
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=27
123
AccountId ID of the account. 0000000-0000-0000-0000-000000000000
Username Username of the user the Marketplace is for. example
Password The users password. P4$$w0rd
AccountName (Optional) If the account ID doesn't exist it will be created, you can include a name for the account otherwise the ID will be used as the 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.
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 A name you wish to give this instance of your Connector installed within the new or existing 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. This is not relevant to all 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": "0000000-0000-0000-0000-000000000000",
    "ExpiresAtUtc": "2020-01-01T12:30:00.000Z",
    "MarketplaceUrl": "https://hostapp.cyclr.com/account/signinwithtoken?token=lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ%3D&returnUrl=%2Flaunch/marketplace/1",
    "Token": "lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ="
}
Response Field Description Example Value
AccountId The ID of the newly created account, or the existing account you provided in your request. 0000000-0000-0000-0000-000000000000
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/1
Token Marketplace URL token. lld3UjpZKkuh0I7ObHR0EtxRsPo0No1GqNSyAi8pqXQ=
Tags:
Edit me